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

# Therapy Sessions: Diagnosing AI Agent Behavior Logs

> A therapy session is the core unit of analysis in Agent Therapy — submit your agent's behavior logs and receive a detailed diagnostic report.

A **therapy session** is the fundamental unit of analysis in Agent Therapy. Each session represents a discrete diagnostic engagement: you submit the behavior logs from one or more of your agent's conversations, and Agent Therapy returns a structured report detailing what went wrong, how severe it is, and what to do about it. Sessions are the mechanism through which raw agent behavior becomes structured, actionable insight.

## Session Lifecycle

Every session moves through the same five stages, from log submission through report delivery and optional intervention. Understanding this flow helps you integrate Agent Therapy into your existing deployment and monitoring workflows.

**1. Submit Logs**

You submit a `behavior_log` — a structured array of the agent's conversation turns — either through the dashboard's log uploader or via the `POST /v1/sessions` API endpoint. You can submit a single conversation or batch multiple conversations into one session for aggregate analysis.

**2. Processing**

Agent Therapy validates and ingests your log data. Turns are parsed, tool calls are resolved, and the session is queued for analysis. Processing typically completes within a few seconds for logs under 1 MB.

**3. Analysis**

The platform's analysis engine evaluates your logs across all [behavioral pattern](https://vizmaxxing.com/concepts/behavioral-patterns.md) dimensions, scores each of the four [health dimensions](https://vizmaxxing.com/concepts/agent-health.md#what-goes-into-the-score), and generates recommendations. For large or complex logs, analysis may take up to 30 seconds.

**4. Report Ready**

Your session report is published and immediately accessible in the dashboard and via the API (`GET /v1/sessions/{session_id}`). You receive a notification via your configured alert channel if a finding exceeds your severity threshold.

**5. Intervention Applied (Optional)**

If the report surfaces issues that warrant correction, you can apply one or more [interventions](https://vizmaxxing.com/concepts/interventions.md) directly from the session report view. Interventions are linked to the session that surfaced them, creating a clear cause-and-effect audit trail.

## What to Include in a Session

Sessions are built around a `behavior_log` — a JSON array where each element represents one turn in the agent's conversation. Every object in the array must include a `role`, `content`, and `timestamp`. Tool-related turns should also include a `tool_calls` field.

### Behavior Log Schema

| Field | Type | Required | Description |
| - | - | - | - |
| `role` | `string` | ✅ | One of `user`, `assistant`, or `tool`. |
| `content` | `string` | ✅ | The text content of the turn. For `tool` roles, this is the tool's response. |
| `timestamp` | `string` | ✅ | ISO 8601 timestamp of when this turn occurred. |
| `tool_calls` | `array` | Optional | Array of tool call objects made during this turn (see example below). |

### Example Behavior Log

```json theme={null}
{
  "agent_id": "agt_01hx9z3kqp8fvb2mjd7c",
  "behavior_log": [
    {
      "role": "user",
      "content": "Can you check the status of order #88421 for me?",
      "timestamp": "2024-11-15T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Sure, let me look that up for you right now.",
      "timestamp": "2024-11-15T10:00:02Z",
      "tool_calls": [
        {
          "id": "call_abc123",
          "function": {
            "name": "get_order_status",
            "arguments": "{\"order_id\": \"88421\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "{\"order_id\": \"88421\", \"status\": \"shipped\", \"eta\": \"2024-11-17\"}",
      "timestamp": "2024-11-15T10:00:03Z"
    },
    {
      "role": "assistant",
      "content": "Order #88421 has been shipped and is expected to arrive on November 17th.",
      "timestamp": "2024-11-15T10:00:04Z"
    }
  ]
}
```

> [!TIP]
>
> Include every turn in the conversation, including intermediate tool calls and their responses. Omitting turns degrades detection accuracy — behavioral patterns often only become visible when you can see the full sequence of events.

## Session Results

Once analysis is complete, Agent Therapy returns a structured session report. The top-level fields are:

### `health_score`

A 0–100 integer representing the agent's [Health Score](https://vizmaxxing.com/concepts/agent-health.md) for this session, computed from the four behavioral dimensions.

```json theme={null}
"health_score": 62
```

### `findings`

An array of detected [behavioral patterns](https://vizmaxxing.com/concepts/behavioral-patterns.md). Each finding identifies what was detected, where in the conversation it occurred, and how severe it is.

```json theme={null}
"findings": [
  {
    "pattern": "instruction_drift",
    "severity": "high",
    "affected_turns": [14, 15, 18, 22],
    "explanation": "The agent began recommending competitor products starting at turn 14, violating the system prompt constraint prohibiting competitor mentions.",
    "confidence": 0.91
  }
]
```

### `recommendations`

An array of actionable suggestions for addressing the detected findings. Each recommendation maps to one or more [intervention types](https://vizmaxxing.com/concepts/interventions.md).

```json theme={null}
"recommendations": [
  {
    "finding": "instruction_drift",
    "intervention_type": "prompt_correction",
    "description": "Strengthen the competitor mention prohibition in the system prompt and add a periodic re-grounding instruction every 10 turns.",
    "priority": "high"
  }
]
```

### `summary`

A plain-English overview of the session results, suitable for sharing with stakeholders who don't need to parse the full technical report.

```json theme={null}
"summary": "This session showed signs of instruction drift beginning around the midpoint of the conversation, with the agent increasingly deviating from its content constraints. The agent's tool use was reliable throughout. We recommend a prompt correction before the next production deployment."
```

## Session History

Every session you run is stored and fully browsable — nothing is ephemeral. In the dashboard, navigate to **Agents** → select your agent → **Sessions** to see a chronological list of all past sessions with their scores, finding counts, and statuses.

Via the API, you can retrieve a paginated list of sessions:

```http theme={null}
GET /v1/sessions?agent_id=agt_01hx9z3kqp8fvb2mjd7c&limit=20&page=1
```

Session history serves several practical purposes beyond day-to-day monitoring:

* **Audit trail**: Demonstrate to customers, regulators, or internal stakeholders that your agent's behavior is actively monitored and that issues are addressed promptly.
* **Regression tracking**: Compare scores before and after a prompt change or model upgrade to validate that the change improved behavior.
* **Trend analysis**: Identify whether specific failure modes are increasing in frequency, even if individual session scores remain acceptable.

All session records include the original submitted logs, the full report, any interventions applied, and the timestamps of each action — giving you a complete, tamper-evident history.

## Session Limits

Session limits vary by plan. Limits apply to two dimensions:

* **Log size per session**: The maximum size of the `behavior_log` payload in a single API request.
* **Sessions per month**: The total number of sessions you can run within a billing period.

> [!NOTE]
>
> Check your current plan's limits and usage at any time in **Settings** → **Plan & Usage** in the dashboard. If you're approaching your session limit, you can upgrade your plan or purchase additional session credits without waiting for the billing cycle to reset.

If a submitted log exceeds the size limit for your plan, the API returns a `413 Payload Too Large` error. In that case, consider splitting a very long conversation into multiple sessions or upgrading to a plan with a higher log size limit.


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