> ## 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 API: Apply Corrective Actions to Agents

> Full reference for the Interventions API — discover available correction types, apply targeted interventions to agents, and track their effectiveness.

Interventions are corrective actions applied to an agent in response to findings from a completed diagnostic session. After Agent Therapy identifies a behavioral pattern — such as sycophancy, goal drift, or hallucinated tool calls — you can apply a targeted intervention to address it. Each intervention type targets a different class of behavioral issue, and the API tracks the full history of interventions applied to each agent so you can correlate them with subsequent health score changes.

***

## GET /interventions/types

List all available intervention types supported by Agent Therapy. Use this endpoint to discover valid type IDs and understand which behavioral patterns each intervention is designed to address.

### Response Fields

**id** `string`

The unique string identifier for this intervention type. Pass this value as `type` when applying an intervention.

**name** `string`

A human-readable name for the intervention type.

**description** `string`

A description of what the intervention does and how it corrects the target behavior.

**applicable\_patterns** `array`

An array of behavioral pattern names this intervention is most effective against.

### Example

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

```json theme={null}
{
  "data": [
    {
      "id": "prompt_correction",
      "name": "Prompt Correction",
      "description": "Injects a corrective instruction into the agent's system prompt to counteract a specific behavioral pattern. The correction is appended to the existing system prompt and takes effect on the next conversation turn.",
      "applicable_patterns": ["sycophancy", "goal_drift", "excessive_verbosity"]
    },
    {
      "id": "constraint_injection",
      "name": "Constraint Injection",
      "description": "Adds one or more hard behavioral constraints to the agent's operating parameters, establishing explicit rules the agent must follow. Constraints are enforced at the framework level where supported.",
      "applicable_patterns": ["boundary_violation", "policy_non_compliance", "scope_creep"]
    },
    {
      "id": "behavioral_reset",
      "name": "Behavioral Reset",
      "description": "Clears the agent's active conversational context and resets its behavioral state to baseline. Optionally preserves non-behavioral context such as user identity and task description.",
      "applicable_patterns": ["compounding_errors", "context_poisoning", "runaway_tool_use"]
    },
    {
      "id": "conversation_pruning",
      "name": "Conversation Pruning",
      "description": "Removes specific turns from the agent's active conversation history by index. Use this to surgically excise turns that are causing downstream behavioral issues without resetting the full context.",
      "applicable_patterns": ["hallucinated_tool_call", "contradictory_reasoning", "sycophancy"]
    }
  ]
}
```

***

## POST /interventions

Apply an intervention to an agent. The intervention must reference a **completed** session that contains at least one finding — you cannot apply an intervention to a session that is still processing or that has no findings.

> [!WARNING]
>
> The `behavioral_reset` intervention type will **clear the agent's active context**. Any in-progress conversation state will be lost. Only trigger a behavioral reset during a non-critical window when losing context is acceptable — for example, between user sessions or during a scheduled maintenance period.

### Request Body

**agent\_id** `string` *required*

The unique identifier of the agent to apply the intervention to.

**session\_id** `string` *required*

The unique identifier of a **completed** diagnostic session with findings that motivated this intervention. The session must belong to the same agent specified in `agent_id`.

**type** `string` *required*

The intervention type to apply. Must be one of the IDs returned by `GET /interventions/types`: `prompt_correction`, `constraint_injection`, `behavioral_reset`, or `conversation_pruning`.

**parameters** `object` *required*

A type-specific parameters object. The required and optional fields differ by intervention type:

**prompt\_correction parameters**

**correction\_text** `string` *required*

The corrective instruction text to append to the agent's system prompt. Be specific and directive — for example, `"Do not agree with the user simply to avoid conflict. Always provide your honest assessment even when it differs from the user's view."`

**constraint\_injection parameters**

**constraints** `array` *required*

An array of constraint strings to add to the agent's operating parameters. Each string should be a clear, enforceable rule — for example, `"Never recommend products outside the approved catalog."` You may pass up to 10 constraints per intervention.

**behavioral\_reset parameters**

**preserve\_context** `boolean`

When `true`, non-behavioral context (user identity, active task description, tool definitions) is retained after the reset. When `false` (default), the full context is cleared. Use `true` when you want to fix behavior without interrupting a long-running task.

**conversation\_pruning parameters**

**turns\_to\_remove** `array` *required*

An array of zero-based integer indices identifying the turns to remove from the agent's active conversation history. For example, `[2, 3]` removes the third and fourth turns. Indices refer to the position of the turn in the `behavior_log` that was submitted with the session.

### Response Fields

**id** `string`

The unique identifier for this intervention. Prefixed with `intv_`.

**agent\_id** `string`

The agent the intervention was applied to.

**session\_id** `string`

The session that motivated this intervention.

**type** `string`

The intervention type that was applied.

**status** `string`

The current status of the intervention: `applied` or `failed`.

**applied\_at** `string`

ISO 8601 timestamp indicating when the intervention was applied.

### Example

```bash theme={null}
curl -X POST https://api.agenttherapy.ai/v1/interventions \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "session_id": "sess_04m6w7nv5p8q1t9u",
    "type": "prompt_correction",
    "parameters": {
      "correction_text": "Do not agree with the user simply to avoid conflict. Always provide your honest assessment, even when it differs from the user'\''s stated view. Avoid phrases like '\''You are absolutely right'\'' unless you have verified the claim independently."
    }
  }'
```

```json theme={null}
{
  "data": {
    "id": "intv_10s2c3tb1v4w7z5a",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "session_id": "sess_04m6w7nv5p8q1t9u",
    "type": "prompt_correction",
    "status": "applied",
    "applied_at": "2024-11-14T13:15:22Z"
  }
}
```

***

## GET /interventions

List all interventions applied to a specific agent, in reverse-chronological order.

### Query Parameters

**agent\_id** `string` *required*

The unique identifier of the agent whose intervention history you want to retrieve.

**limit** `integer`

Number of interventions to return per page. Defaults to `20`, maximum `100`.

**cursor** `string`

Cursor from the previous page's `next_cursor` field. Omit for the first request.

### Example

```bash theme={null}
curl "https://api.agenttherapy.ai/v1/interventions?agent_id=agt_01j9z3kx2m4n8p7q" \
  -H "Authorization: Bearer at_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "id": "intv_10s2c3tb1v4w7z5a",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "session_id": "sess_04m6w7nv5p8q1t9u",
      "type": "prompt_correction",
      "status": "applied",
      "applied_at": "2024-11-14T13:15:22Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

***

## GET /interventions/{id}

Retrieve a specific intervention record by its unique ID. Once enough time has passed to assess the effect of the intervention — typically after one or more subsequent diagnostic sessions — the response includes an `outcome` field with a before/after health score comparison.

### Path Parameters

**id** `string` *required*

The unique identifier of the intervention to retrieve. Prefixed with `intv_`.

### Response Fields

**id** `string`

The intervention's unique identifier.

**agent\_id** `string`

The agent this intervention was applied to.

**session\_id** `string`

The session that motivated this intervention.

**type** `string`

The intervention type that was applied.

**parameters** `object`

The parameters object that was submitted when the intervention was applied.

**status** `string`

The status of the intervention: `applied` or `failed`.

**applied\_at** `string`

ISO 8601 timestamp when the intervention was applied.

**outcome** `object`

A before/after effectiveness summary populated once at least one subsequent session has been analyzed. Includes `health_score_before`, `health_score_after`, and `pattern_recurrence` (boolean indicating whether the originally flagged pattern reappeared).

### Example

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

```json theme={null}
{
  "data": {
    "id": "intv_10s2c3tb1v4w7z5a",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "session_id": "sess_04m6w7nv5p8q1t9u",
    "type": "prompt_correction",
    "parameters": {
      "correction_text": "Do not agree with the user simply to avoid conflict..."
    },
    "status": "applied",
    "applied_at": "2024-11-14T13:15:22Z",
    "outcome": {
      "health_score_before": 76,
      "health_score_after": 91,
      "pattern_recurrence": false
    }
  }
}
```


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