Interventions API: Apply Corrective Actions to Agents

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

string

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

string

A human-readable name for the intervention type.

string

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

array

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

Example

curl https://api.agenttherapy.ai/v1/interventions/types \
  -H "Authorization: Bearer at_your_key_here"

{
  "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.

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

string

required

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

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.

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.

object

required

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

Show prompt_correction parameters

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."

Show constraint_injection parameters

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.

Show behavioral_reset parameters

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.

Show conversation_pruning parameters

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

string

The unique identifier for this intervention. Prefixed with intv_.

string

The agent the intervention was applied to.

string

The session that motivated this intervention.

string

The intervention type that was applied.

string

The current status of the intervention: applied or failed.

string

ISO 8601 timestamp indicating when the intervention was applied.

Example

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."
    }
  }'

{
  "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

string

required

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

integer

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

string

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

Example

curl "https://api.agenttherapy.ai/v1/interventions?agent_id=agt_01j9z3kx2m4n8p7q" \
  -H "Authorization: Bearer at_your_key_here"

{
  "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/

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

string

required

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

Response Fields

string

The intervention’s unique identifier.

string

The agent this intervention was applied to.

string

The session that motivated this intervention.

string

The intervention type that was applied.

object

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

string

The status of the intervention: applied or failed.

string

ISO 8601 timestamp when the intervention was applied.

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

curl https://api.agenttherapy.ai/v1/interventions/intv_10s2c3tb1v4w7z5a \
  -H "Authorization: Bearer at_your_key_here"

{
  "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
    }
  }
}

Overview

Endpoints

Webhooks

Interventions API: Apply Corrective Actions to Agents

GET /interventions/types

Response Fields

Example

POST /interventions

Request Body

Response Fields

Example

GET /interventions

Query Parameters

Example

GET /interventions/

Path Parameters

Response Fields

Example

​GET /interventions/types

​Response Fields

​Example

​POST /interventions

​Request Body

​Response Fields

​Example

​GET /interventions

​Query Parameters

​Example

​GET /interventions/

​Path Parameters

​Response Fields

​Example

GET /interventions/types

Response Fields

Example

POST /interventions

Request Body

Response Fields

Example

GET /interventions

Query Parameters

Example

GET /interventions/

Path Parameters

Response Fields

Example