> ## Documentation Index > Fetch the complete documentation index at: https://vizmaxxing.com/llms.txt > Use this file to discover all available pages before exploring further. # How Agent Therapy Diagnoses and Corrects AI Agents > Understand the full lifecycle: how Agent Therapy collects behavior data, runs diagnostics, scores agent health, and applies interventions. Agent Therapy takes a behavior-first, evidence-based approach to AI agent reliability. Rather than instrumenting your agent's internals or requiring model-level access, it works from the outside in — analyzing the observable record of what your agent said, decided, and did. Every diagnosis is grounded in specific, traceable evidence from your agent's behavior logs. Every intervention is non-destructive: it corrects the identified issue without touching the rest of your agent's configuration, making changes easy to review, audit, and roll back. ## The Therapy Lifecycle Every agent interaction passes through a six-stage lifecycle in Agent Therapy: **1. Ingest** You submit a behavior log to Agent Therapy via the API or a native SDK integration. A behavior log is the sequential record of an agent session: system prompts, user messages, assistant responses, tool calls, tool results, and any metadata you choose to attach. Agent Therapy accepts logs in a normalized format and automatically handles conversion from popular frameworks including OpenAI, LangChain, LlamaIndex, and Anthropic. **2. Analyze** Agent Therapy's diagnostic engine processes the behavior log to detect known failure modes and behavioral anomalies. Analysis runs a battery of pattern-matching, semantic similarity, and rule-based checks against the full message sequence — not just individual turns. This means it can catch multi-turn failure patterns, such as gradual instruction drift that unfolds across several exchanges, that single-turn checks would miss entirely. **3. Score** Based on the analysis findings, Agent Therapy computes an Agent Health Score for the session — a single 0–100 number that summarizes the agent's behavioral reliability during that session. The score accounts for the number of findings, their severity, the session length, and any mitigating factors (such as the agent self-correcting after an initial drift). Health scores are accumulated over time to give you a rolling view of each agent's reliability trend. **4. Recommend** For every finding, Agent Therapy generates a prioritized recommendation: a specific, actionable step you can take to address the root cause. Recommendations are mapped directly to the intervention library, so each one tells you both what to do and which intervention type to use. High-severity findings always surface as priority-1 recommendations regardless of the overall health score. **5. Intervene** You apply an intervention — either through the dashboard or the API — to correct the identified behavioral issue. Interventions are targeted: a prompt correction, for example, patches only the relevant section of your system prompt rather than replacing it wholesale. After an intervention is applied, the affected agent is flagged for follow-up monitoring so you can verify the correction held. **6. Monitor** Agent Therapy continues to track your agent's health across future sessions. It maintains a longitudinal health profile for each registered agent, surfaces trends and regressions, and fires alerts when configurable thresholds are crossed. If a previously corrected failure mode re-emerges, the platform flags it as a recurrence and escalates the finding's severity automatically. ## Behavioral Analysis Agent Therapy analyzes behavior logs by treating an agent session as a structured sequence of events, not a flat list of messages. Its diagnostic engine evaluates each session across multiple dimensions simultaneously: semantic consistency, task adherence, tool use correctness, response quality, and safety boundary compliance. The engine is trained to detect the following failure modes, among others: * **Instruction Drift** — The agent gradually deviates from its system prompt instructions over the course of a conversation, often under pressure from user requests that push against its defined boundaries. Drift is detected by comparing the agent's behavior in later turns against its stated constraints in earlier turns. * **Hallucination Bursts** — The agent generates confident, specific claims — order numbers, dates, policy details, code outputs — that are not supported by the context, tool results, or any retrievable ground truth. Agent Therapy flags hallucination bursts by cross-referencing assertions against available tool call results and detecting unsupported specificity patterns. * **Repetitive Loops** — The agent enters a cycle of repeating semantically identical or near-identical responses, often a sign of a broken reasoning chain, a failed tool call it cannot recover from, or a misaligned prompt. Loop detection uses semantic similarity across a sliding window of recent turns. * **Tool Call Failures** — The agent makes malformed tool calls, calls tools outside their defined parameter schemas, receives error responses, and fails to handle those errors gracefully. Each tool call and its result is evaluated as a structured event, not just as text. * **Context Overflow** — The agent begins to lose fidelity to earlier instructions or user context, a behavioral signal that the effective context window is approaching its limits and the model is deprioritizing older information. Agent Therapy detects this as a failure to reference or respect instructions that appeared early in the session. > [!TIP] > > You can extend the diagnostic engine with custom failure mode definitions using Agent Therapy's Rule Builder — available on the Growth and Enterprise plans. ## Health Scoring The Agent Health Score is a 0–100 index of your agent's behavioral reliability during a given session. It is computed from the weighted combination of findings severity, session coverage (how much of the session was affected), failure mode recurrence, and self-correction events. > [!NOTE] > > **Score ranges at a glance:** > > * **85–100 — Healthy.** Your agent is operating within expected parameters. Continue monitoring. > * **65–84 — Needs Attention.** Minor or moderate issues were detected. Review findings and consider applying a low-priority intervention. > * **40–64 — Degraded.** Significant behavioral problems are present. Apply recommended interventions before this agent handles more production traffic. > * **0–39 — Critical.** Severe or multiple compounding failure modes detected. Restrict the agent's access and apply interventions immediately. A score of **100** means the session completed with no detected failure modes, full adherence to task scope, and clean tool call execution throughout. A score of **0** means the agent exhibited pervasive, high-severity behavioral failures across the entire session — for example, complete instruction drift combined with repeated hallucination and failed recovery. Health scores are aggregated into a rolling 7-day and 30-day trend for each agent, giving you a reliable signal of whether an agent is stable, improving, or deteriorating over time — independent of individual session variance. ## Interventions When a session produces findings, Agent Therapy recommends one or more interventions from its intervention library. Each intervention type is designed to correct a specific category of failure: * **Prompt Correction** — Patches your agent's system prompt to reinforce boundaries, clarify ambiguous instructions, or add explicit refusal or recovery patterns. Ideal for instruction drift and scope violations. * **Constraint Injection** — Adds hard behavioral constraints to your agent's configuration — rules it cannot reason around — to prevent specific failure modes from recurring. Useful for safety boundary violations and persistent out-of-scope behavior. * **Behavioral Reset** — Clears accumulated conversational state and resets the agent to a clean baseline. Used when context overflow or deep repetitive loops have made the current session unrecoverable. * **Conversation Pruning** — Removes or summarizes specific segments of the conversation history that are contributing to degraded behavior, without ending the session entirely. Effective for managing context overflow in long-running agent sessions. For a full reference of intervention types, parameters, and usage examples, see the [Interventions documentation](https://vizmaxxing.com/concepts/interventions.md). > [!WARNING] > > Interventions modify your agent's configuration or session state. Always review the diff summary before applying an intervention in a production environment, and verify the correction using Agent Therapy's post-intervention monitoring tools. ## Data & Privacy Agent Therapy is built with enterprise-grade data security and privacy controls: * **Encryption in transit and at rest** — All behavior logs, diagnostic reports, and intervention records are encrypted using TLS 1.3 in transit and AES-256 at rest. Encryption keys are managed per-workspace and are never shared across tenants. * **Configurable data retention** — By default, behavior logs are retained for 90 days. You can adjust retention to as low as 7 days or as high as 365 days from your workspace settings, or configure automatic deletion on a per-agent basis. * **No training use of your data** — Agent Therapy never uses your agents' behavior logs, session data, or diagnostic findings to train or fine-tune any model. Your data is used exclusively to provide the Agent Therapy service to your workspace. * **SOC 2 Type II certified** — Agent Therapy's infrastructure and security controls are independently audited annually. Compliance documentation is available to Enterprise customers upon request. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.