Therapy Sessions: Diagnosing AI Agent Behavior Logs

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.

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.

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.

Analysis

The platform’s analysis engine evaluates your logs across all behavioral pattern dimensions, scores each of the four health dimensions, and generates recommendations. For large or complex logs, analysis may take up to 30 seconds.

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.

Intervention Applied (Optional)

If the report surfaces issues that warrant correction, you can apply one or more interventions 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

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

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 for this session, computed from the four behavioral dimensions.

"health_score": 62

`findings`

An array of detected behavioral patterns. Each finding identifies what was detected, where in the conversation it occurred, and how severe it is.

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

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

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

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.

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.

Get Started

Core Concepts

Guides

Integrations

Support

Therapy Sessions: Diagnosing AI Agent Behavior Logs

Session Lifecycle

What to Include in a Session

Behavior Log Schema

Example Behavior Log

Session Results

`health_score`

`findings`

`recommendations`

`summary`

Session History

Session Limits

​Session Lifecycle

​What to Include in a Session

​Behavior Log Schema

​Example Behavior Log

​Session Results

​health_score

​findings

​recommendations

​summary

​Session History

​Session Limits

Session Lifecycle

What to Include in a Session

Behavior Log Schema

Example Behavior Log

Session Results

`health_score`

`findings`

`recommendations`

`summary`

Session History

Session Limits