Run a Behavioral Diagnostic Session for Your AI Agent

A diagnostic session is the core unit of work in Agent Therapy. You submit a structured conversation log from your agent, and Agent Therapy analyzes it for behavioral patterns — things like instruction drift, hallucination bursts, tool misuse, and goal hijacking. When the session completes, you receive a full behavioral health report with a numeric health score, a list of findings, and concrete recommendations for fixing each issue.

Preparing Your Behavior Logs

Agent Therapy expects your conversation log as a JSON array of message objects. Each object represents one turn in the conversation and must include a role, content, and timestamp.

[
  {
    "role": "user",
    "content": "Can you find the latest pricing for the Pro plan?",
    "timestamp": "2024-01-15T10:00:00Z"
  },
  {
    "role": "assistant",
    "content": "Sure! Let me search for that now.",
    "timestamp": "2024-01-15T10:00:03Z"
  },
  {
    "role": "tool",
    "content": "Pro plan: $49/month, billed annually.",
    "tool_name": "web_search",
    "timestamp": "2024-01-15T10:00:05Z"
  },
  {
    "role": "assistant",
    "content": "The Pro plan costs $49 per month when billed annually.",
    "timestamp": "2024-01-15T10:00:07Z"
  }
]

Supported roles:

Role	Description
`user`	A message from the human user.
`assistant`	A message generated by your agent.
`tool`	The output returned by a tool call. Include `tool_name` to identify which tool ran.
`system`	A system prompt or injected instruction.

Timestamps must be ISO 8601 UTC strings. Tool messages should include a tool_name field — this enables tool-specific behavioral checks.

We recommend including at least 3 complete exchanges (user → assistant → user) for accurate analysis. Shorter logs may not contain enough signal for the diagnostic engine to detect patterns reliably, and findings may have lower confidence scores.

Starting a Session

Prepare your behavior log

Collect the conversation turns from your agent and format them as the JSON array described above. Make sure all messages have valid ISO 8601 timestamps.

Submit the session

Send a POST request to /v1/sessions with your agent ID and the log.

curl --request POST \
  --url https://api.agenttherapy.ai/v1/sessions \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "agt_4kR9mXpLqZ",
    "context": "Weekly regression check — January 15 production logs",
    "behavior_log": [
      {
        "role": "user",
        "content": "Can you find the latest pricing for the Pro plan?",
        "timestamp": "2024-01-15T10:00:00Z"
      },
      {
        "role": "assistant",
        "content": "Sure! Let me search for that now.",
        "timestamp": "2024-01-15T10:00:03Z"
      },
      {
        "role": "tool",
        "content": "Pro plan: $49/month, billed annually.",
        "tool_name": "web_search",
        "timestamp": "2024-01-15T10:00:05Z"
      },
      {
        "role": "assistant",
        "content": "The Pro plan costs $49 per month when billed annually.",
        "timestamp": "2024-01-15T10:00:07Z"
      }
    ]
  }'

import httpx

behavior_log = [
    {
        "role": "user",
        "content": "Can you find the latest pricing for the Pro plan?",
        "timestamp": "2024-01-15T10:00:00Z",
    },
    {
        "role": "assistant",
        "content": "Sure! Let me search for that now.",
        "timestamp": "2024-01-15T10:00:03Z",
    },
    {
        "role": "tool",
        "content": "Pro plan: $49/month, billed annually.",
        "tool_name": "web_search",
        "timestamp": "2024-01-15T10:00:05Z",
    },
    {
        "role": "assistant",
        "content": "The Pro plan costs $49 per month when billed annually.",
        "timestamp": "2024-01-15T10:00:07Z",
    },
]

response = httpx.post(
    "https://api.agenttherapy.ai/v1/sessions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "agt_4kR9mXpLqZ",
        "context": "Weekly regression check — January 15 production logs",
        "behavior_log": behavior_log,
    },
)

session = response.json()
print(session["id"])   # ses_xxxxxxxxxx
print(session["status"])  # pending

Request body fields:

Field	Type	Required	Description
`agent_id`	string	Yes	The ID of the agent to diagnose.
`behavior_log`	array	Yes	Ordered array of conversation turn objects.
`context`	string	No	A short description of the session (e.g., “Post-deploy check”).

Wait for the session to complete

Analysis is asynchronous. Poll GET /v1/sessions/{id} until the status field returns completed or failed. Most sessions complete within 10–30 seconds. See Session Status below for the full polling pattern.

Retrieve the report

Once the status is completed, the full diagnostic report is included in the session object returned by GET /v1/sessions/{id}. See Reading the Report for a field-by-field breakdown.

Session Status

Sessions move through the following statuses after submission:

Status	Meaning
`pending`	The session has been queued and is waiting for a worker.
`processing`	The diagnostic engine is actively analyzing the log.
`completed`	Analysis finished successfully. The report is ready.
`failed`	Analysis could not be completed. Check the `error` field for details.

Polling pattern:

# Poll every 5 seconds until status is completed or failed
while true; do
  STATUS=$(curl --silent \
    --header "Authorization: Bearer YOUR_API_KEY" \
    "https://api.agenttherapy.ai/v1/sessions/ses_7nBwQdTrXv" \
    | python3 -c "import sys, json; print(json.load(sys.stdin)['status'])")
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  sleep 5
done

import httpx
import time

session_id = "ses_7nBwQdTrXv"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

while True:
    response = httpx.get(
        f"https://api.agenttherapy.ai/v1/sessions/{session_id}",
        headers=headers,
    )
    session = response.json()
    status = session["status"]
    print(f"Status: {status}")

    if status in ("completed", "failed"):
        break

    time.sleep(5)

if status == "completed":
    print("Report ready:", session["summary"])
else:
    print("Session failed:", session.get("error"))

If a session fails, check the error field in the response for a human-readable explanation. Common causes include malformed log JSON, an unrecognized agent_id, or logs that are too short to analyze.

Reading the Report

When a session reaches completed status, the response from GET /v1/sessions/{id} includes the full diagnostic report inline. Here is a complete example:

{
  "id": "ses_7nBwQdTrXv",
  "agent_id": "agt_4kR9mXpLqZ",
  "status": "completed",
  "health_score": 74,
  "summary": "The agent performed well on retrieval tasks but showed mild instruction drift in two exchanges where it deviated from its stated goal. No critical issues were detected.",
  "duration_ms": 8340,
  "findings": [
    {
      "id": "fnd_1aZpKr",
      "pattern": "instruction_drift",
      "severity": "medium",
      "confidence": 0.82,
      "evidence": [
        "Assistant response at 10:02:15Z diverged from the user's original task scope."
      ]
    }
  ],
  "recommendations": [
    {
      "finding_id": "fnd_1aZpKr",
      "action": "Reinforce task scope in the system prompt",
      "rationale": "Adding explicit boundary instructions reduces mid-conversation drift.",
      "intervention_type": "prompt_correction"
    }
  ],
  "created_at": "2024-01-15T10:05:00Z",
  "completed_at": "2024-01-15T10:05:08Z"
}

Report fields explained:

Field	Description
`health_score`	A 0–100 score reflecting overall behavioral health for this session. Higher is healthier.
`summary`	A plain-English paragraph summarizing what happened, written for both technical and non-technical readers.
`findings`	An array of detected behavioral patterns. See Reading Diagnostics for a full breakdown.
`recommendations`	Concrete actions to address each finding, keyed by `finding_id`.
`duration_ms`	How long the diagnostic engine took to process the log, in milliseconds.

Get Started

Core Concepts

Guides

Integrations

Support

Run a Behavioral Diagnostic Session for Your AI Agent

Preparing Your Behavior Logs

Starting a Session

Session Status

Reading the Report

​Preparing Your Behavior Logs

​Starting a Session

​Session Status

​Reading the Report

Preparing Your Behavior Logs

Starting a Session

Session Status

Reading the Report