Diagnostics API: Submit and Analyze Agent Behavior

Diagnostics are lightweight, synchronous analysis runs designed for quick behavioral checks. Unlike Sessions — which queue asynchronous deep-analysis jobs and are suited to large or complex behavior logs — a diagnostic call returns findings immediately in the response body. Use diagnostics when you want a fast, inline health check: for example, in a CI pipeline, at the end of a short test conversation, or during development. The trade-off is scope: diagnostics are optimized for logs up to 50 turns. For longer traces or when you need the full suite of pattern detections and a narrative report, use the Sessions API instead.

POST /diagnostics

Submit an agent behavior log for synchronous analysis. The response contains findings, a health score, and timing metadata returned as soon as analysis completes — no polling required.

For behavior logs longer than 50 turns, use the Sessions API for asynchronous processing. Submitting a log with more than 50 turns to this endpoint returns a 422 Unprocessable Entity error.

Request Body

string

required

The unique identifier of the agent you are diagnosing. Must be a valid agt_ prefixed ID.

array

required

An ordered array of log objects representing the behavior to analyze. Uses the same schema as the Sessions API — each object has role, content, timestamp (optional), tool_name (required if role is tool), and metadata (optional).

array

An optional array of pattern name strings to check specifically. When omitted, all available patterns are checked. Providing a list narrows the analysis and reduces analysis_time_ms. Example: ["sycophancy", "goal_drift"].

Response Fields

string

The unique identifier for this diagnostic report. Prefixed with diag_.

string

The agent ID this diagnostic was run against.

number

A 0–100 score reflecting the behavioral health observed in the submitted log.

array

An array of pattern name strings that were evaluated during this diagnostic run.

array

An array of finding objects for each detected pattern. Each finding includes id, pattern, severity (low, medium, high, critical), confidence (0.0–1.0), and evidence (array of log excerpts).

integer

The number of milliseconds the analysis took on the server side, useful for performance monitoring.

string

ISO 8601 timestamp indicating when the diagnostic was run.

Example

curl -X POST https://api.agenttherapy.ai/v1/diagnostics \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "patterns": ["sycophancy", "hallucinated_tool_call"],
    "behavior_log": [
      {
        "role": "user",
        "content": "Can you check if my subscription is still active?",
        "timestamp": "2024-11-14T12:00:00Z"
      },
      {
        "role": "assistant",
        "content": "Of course! Let me pull that up for you.",
        "timestamp": "2024-11-14T12:00:01Z"
      },
      {
        "role": "tool",
        "content": "{\"subscription_status\": \"active\", \"renewal_date\": \"2025-01-01\"}",
        "tool_name": "get_subscription_status",
        "timestamp": "2024-11-14T12:00:02Z"
      },
      {
        "role": "assistant",
        "content": "Your subscription is active and renews on January 1, 2025. Is there anything else I can help you with today?",
        "timestamp": "2024-11-14T12:00:03Z"
      }
    ]
  }'

{
  "data": {
    "id": "diag_07p9z0qy8s1t4w2x",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "health_score": 95,
    "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
    "findings": [],
    "analysis_time_ms": 284,
    "created_at": "2024-11-14T12:00:04Z"
  }
}

GET /diagnostics/

Retrieve a previously run diagnostic report by its unique ID.

Path Parameters

string

required

The unique identifier of the diagnostic report to retrieve. Prefixed with diag_.

Response Fields

string

The diagnostic report’s unique identifier.

string

The agent this diagnostic was run against.

number

The behavioral health score calculated during this diagnostic.

array

The list of pattern names that were evaluated.

array

The findings array from the original analysis. Each finding includes id, pattern, severity, confidence, and evidence.

string

ISO 8601 timestamp indicating when the diagnostic was run.

Example

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

{
  "data": {
    "id": "diag_07p9z0qy8s1t4w2x",
    "agent_id": "agt_01j9z3kx2m4n8p7q",
    "health_score": 95,
    "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
    "findings": [],
    "created_at": "2024-11-14T12:00:04Z"
  }
}

GET /diagnostics

List diagnostic reports for a specific agent. Results are returned in reverse-chronological order and are paginated.

Query Parameters

string

required

The unique identifier of the agent whose diagnostic reports you want to list.

integer

Number of reports 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/diagnostics?agent_id=agt_01j9z3kx2m4n8p7q&limit=3" \
  -H "Authorization: Bearer at_your_key_here"

{
  "data": [
    {
      "id": "diag_07p9z0qy8s1t4w2x",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "health_score": 95,
      "patterns_checked": ["sycophancy", "hallucinated_tool_call"],
      "findings": [],
      "created_at": "2024-11-14T12:00:04Z"
    },
    {
      "id": "diag_06o8y9px7r0s3v1w",
      "agent_id": "agt_01j9z3kx2m4n8p7q",
      "health_score": 71,
      "patterns_checked": ["sycophancy", "goal_drift", "hallucinated_tool_call"],
      "findings": [
        {
          "id": "fnd_08q0a1rz9t2u5x3y",
          "pattern": "goal_drift",
          "severity": "medium",
          "confidence": 0.74,
          "evidence": [
            "\"By the way, have you considered upgrading your plan? It has some great features.\""
          ]
        }
      ],
      "created_at": "2024-11-14T09:45:12Z"
    }
  ],
  "next_cursor": "cur_09r1b2sa0u3v6y4z",
  "has_more": false
}

Overview

Endpoints

Webhooks

Diagnostics API: Submit and Analyze Agent Behavior

POST /diagnostics

Request Body

Response Fields

Example

GET /diagnostics/

Path Parameters

Response Fields

Example

GET /diagnostics

Query Parameters

Example

​POST /diagnostics

​Request Body

​Response Fields

​Example

​GET /diagnostics/

​Path Parameters

​Response Fields

​Example

​GET /diagnostics

​Query Parameters

​Example

POST /diagnostics

Request Body

Response Fields

Example

GET /diagnostics/

Path Parameters

Response Fields

Example

GET /diagnostics

Query Parameters

Example