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

# Run a Behavioral Diagnostic Session for Your AI Agent

> Submit your agent's conversation logs to Agent Therapy and receive a behavioral health report with detected issues and recommendations.

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

```json theme={null}
[
  {
    "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.

> [!NOTE]
>
> 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

**1. 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.

**2. Submit the session**

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

```bash curl theme={null}
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"
      }
    ]
  }'
```

```python Python theme={null}
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"). |

**3. 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](#session-status) below for the full polling pattern.

**4. 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](#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:**

```bash curl theme={null}
# 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
```

```python Python theme={null}
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:

```json theme={null}
{
  "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](https://vizmaxxing.com/guides/reading-diagnostics.md) 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. |


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