> ## Documentation Index
> Fetch the complete documentation index at: https://vizmaxxing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interventions: Applying Corrective Actions to Agents

> Interventions are targeted corrective actions that Agent Therapy applies to fix identified behavioral issues without requiring a full agent rebuild.

An **intervention** is a targeted, evidence-based corrective action that Agent Therapy applies to address a specific behavioral problem identified in your agent. Rather than rebuilding your agent from scratch or guessing at what went wrong, interventions are precise — grounded in the findings from a diagnostic session and designed to correct the identified issue while leaving healthy behavior untouched. Each intervention type targets a different class of problem, so you apply the right fix for the right failure mode every time.

## Intervention Types

> **Prompt Correction**
>
> **Rewrites or supplements your agent's system prompt** to address instruction drift, goal abandonment, or behavior that contradicts the agent's intended role. Agent Therapy generates a specific prompt amendment based on the session findings — you review it, edit if needed, and apply it.
>
> Best for: [Instruction Drift](https://vizmaxxing.com/concepts/behavioral-patterns.md), [Goal Abandonment](https://vizmaxxing.com/concepts/behavioral-patterns.md), [Hallucination Burst](https://vizmaxxing.com/concepts/behavioral-patterns.md)

> **Constraint Injection**
>
> **Adds targeted guardrails to the agent's active context** to prevent a specific failure behavior from continuing. Unlike a full prompt rewrite, constraint injection inserts a focused, scoped directive — for example, a prohibition on making a certain type of tool call, or an instruction to express uncertainty in a particular domain.
>
> Best for: [Hallucination Burst](https://vizmaxxing.com/concepts/behavioral-patterns.md), [Tool Call Failure Cascade](https://vizmaxxing.com/concepts/behavioral-patterns.md)

> **Behavioral Reset**
>
> **Clears the agent's current conversation context** to break out of a repetitive loop or stop a cascading failure from compounding further. The agent restarts with a clean context, re-grounded in its system prompt. Behavioral Reset is the fastest way to stop active dysfunction.
>
> Best for: [Repetitive Loop](https://vizmaxxing.com/concepts/behavioral-patterns.md), [Tool Call Failure Cascade](https://vizmaxxing.com/concepts/behavioral-patterns.md)

> **Conversation Pruning**
>
> **Removes specific turns from the agent's context window** — typically low-value exchanges, erroneous tool responses, or turns that are crowding out critical early context. Unlike a full reset, pruning preserves the conversational thread while freeing up context space and removing noise.
>
> Best for: [Context Overflow](https://vizmaxxing.com/concepts/behavioral-patterns.md), [Repetitive Loop](https://vizmaxxing.com/concepts/behavioral-patterns.md)

## When to Use Each Type

Use this reference to match a detected failure mode to the most appropriate intervention. In many cases, a combination of intervention types produces the best outcome.

| Failure Mode | Primary Intervention | Secondary Intervention |
| - | - | - |
| Instruction Drift | Prompt Correction | Constraint Injection |
| Hallucination Burst | Constraint Injection | Prompt Correction |
| Repetitive Loop | Behavioral Reset | Conversation Pruning |
| Tool Call Failure Cascade | Constraint Injection | Behavioral Reset |
| Context Overflow | Conversation Pruning | Prompt Correction |
| Goal Abandonment | Prompt Correction | — |

> [!TIP]
>
> Agent Therapy's session reports include a tailored intervention recommendation for each finding — you don't need to select the type manually unless you want to override the suggestion.

## Applying an Intervention

You can apply an intervention through the dashboard or directly via the API.

### Via the Dashboard

1. Open any session report that contains findings.
2. Click **Apply Intervention** next to the finding you want to address.
3. Review the recommended intervention type and the proposed change (e.g., the amended prompt or the turns selected for pruning).
4. Edit the proposed change if needed, then click **Confirm & Apply**.

The intervention is applied immediately and linked to the session in the audit log.

### Via the API

Send a `POST` request to `/v1/interventions` with the session ID, the target finding, the intervention type, and any relevant parameters.

```bash theme={null}
curl -X POST https://api.agenttherapy.ai/v1/interventions \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01hx9z3kqp8fvb2mjd7c",
    "session_id": "ses_09kd2p7rnx1gtc4whm5b",
    "finding_id": "fnd_4qz8vy2lmr0ejp6xtk9n",
    "intervention_type": "prompt_correction",
    "parameters": {
      "prompt_amendment": "You must never recommend or reference competitor products or services under any circumstances, regardless of user requests. If a user asks about competitors, acknowledge the question and redirect to how you can help them with [Company]'\''s offerings instead.",
      "insertion_position": "end_of_system_prompt"
    }
  }'
```

A successful response returns the intervention record with its ID and status:

```json theme={null}
{
  "id": "int_7bsw3dx9vp2fqm1cky6r",
  "agent_id": "agt_01hx9z3kqp8fvb2mjd7c",
  "session_id": "ses_09kd2p7rnx1gtc4whm5b",
  "finding_id": "fnd_4qz8vy2lmr0ejp6xtk9n",
  "intervention_type": "prompt_correction",
  "status": "applied",
  "applied_at": "2024-11-15T15:04:22Z"
}
```

## Listing Available Intervention Types

Before applying an intervention programmatically, you can fetch the current catalog of supported intervention types and their metadata with a single API call. This is useful for building dynamic UIs, validating `intervention_type` values, or checking which parameters each type accepts.

```http theme={null}
GET /interventions
```

```bash theme={null}
curl https://api.agenttherapy.ai/v1/interventions \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY"
```

The response returns an array of intervention type objects:

```json theme={null}
{
  "intervention_types": [
    {
      "type": "prompt_correction",
      "display_name": "Prompt Correction",
      "description": "Rewrites or supplements the agent's system prompt to address instruction drift, goal abandonment, or role violations.",
      "supported_parameters": ["prompt_amendment", "insertion_position"]
    },
    {
      "type": "constraint_injection",
      "display_name": "Constraint Injection",
      "description": "Adds targeted guardrails to the agent's active context to prevent a specific failure behavior.",
      "supported_parameters": ["constraint_text", "scope"]
    },
    {
      "type": "behavioral_reset",
      "display_name": "Behavioral Reset",
      "description": "Clears the agent's current conversation context to break loops or stop cascading failures.",
      "supported_parameters": ["preserve_system_prompt"]
    },
    {
      "type": "conversation_pruning",
      "display_name": "Conversation Pruning",
      "description": "Removes specific turns from the agent's context window to free space and eliminate noise.",
      "supported_parameters": ["turns_to_remove", "pruning_strategy"]
    }
  ]
}
```

## Intervention History

Every intervention is permanently logged and linked to the session that prompted it. In the dashboard, navigate to **Agents** → select your agent → **Interventions** to see a full chronological history including the intervention type, the finding it addressed, who applied it, and when.

Via the API, retrieve intervention history for an agent:

```http theme={null}
GET /v1/interventions?agent_id=agt_01hx9z3kqp8fvb2mjd7c
```

This history is an important part of your agent's operational record. It allows you to:

* **Verify that issues were addressed** — reviewers can see that a reported problem was acted on.
* **Correlate interventions with score changes** — confirm that an intervention improved the Health Score in subsequent sessions.
* **Demonstrate compliance** — provide auditors with a full timeline of detected issues and corrective actions taken.

> [!WARNING]
>
> **Some interventions affect live agent sessions.** Behavioral Reset in particular immediately clears the active context of any ongoing conversation your agent is currently handling — users mid-session will experience a context break. Always review the scope of an intervention in the preview screen before applying it in a production environment. If possible, schedule disruptive interventions during low-traffic windows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.