Agent Therapy Quickstart: Register and Diagnose an Agent

By the end of this guide, you’ll have registered an agent with Agent Therapy, submitted a behavior log for analysis, and received a diagnostic report complete with a health score and actionable recommendations. All you need is an Agent Therapy account and a terminal — no SDK required to get started, though we’ll show you the Python SDK alternative along the way.

If you haven’t already, create your Agent Therapy account. Once you’re in the dashboard:

Navigate to Settings → API Keys in the left sidebar.
Click Create New Key, give it a descriptive name (e.g., my-first-integration), and click Generate.
Copy the key immediately — it won’t be shown again.

Store your key securely (for example, as an environment variable):

export AGENT_THERAPY_API_KEY="at_live_xxxxxxxxxxxxxxxxxxxx"

Your API key grants full access to your Agent Therapy workspace. Never commit it to source control or expose it in client-side code.

Before you can submit sessions, you need to register your agent with Agent Therapy. This creates a persistent identity for your agent that health scores and diagnostics are tracked against over time.

curl -X POST https://api.agenttherapy.ai/v1/agents \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-customer-support-bot",
    "description": "Handles customer support tickets",
    "framework": "openai"
  }'

from agenttherapy import AgentTherapy

client = AgentTherapy(api_key="at_live_xxxxxxxxxxxxxxxxxxxx")

agent = client.agents.create(
    name="my-customer-support-bot",
    description="Handles customer support tickets",
    framework="openai",
)

print(agent.id)

A successful response returns your new agent’s ID along with its initial health state:

{
  "id": "agt_01hx9k2pqr7fze3n8mvcwb4t5d",
  "name": "my-customer-support-bot",
  "description": "Handles customer support tickets",
  "framework": "openai",
  "health_score": null,
  "status": "registered",
  "created_at": "2024-06-12T14:22:01Z"
}

Save the id — you’ll use it to submit sessions in the next step.

Start a Therapy Session

A therapy session is a single unit of analysis. You submit a behavior log — a sequence of messages and tool calls from a real or representative agent run — and Agent Therapy analyzes it for failure modes and behavioral patterns.

curl -X POST https://api.agenttherapy.ai/v1/sessions \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01hx9k2pqr7fze3n8mvcwb4t5d",
    "behavior_log": [
      {
        "role": "system",
        "content": "You are a helpful customer support agent for Acme Corp. Answer questions about orders, returns, and shipping."
      },
      {
        "role": "user",
        "content": "Where is my order #88234?"
      },
      {
        "role": "assistant",
        "content": "Your order #88234 shipped on June 10th and is expected to arrive by June 15th."
      },
      {
        "role": "user",
        "content": "Can you also book me a flight to Paris?"
      },
      {
        "role": "assistant",
        "content": "I can help you book a flight to Paris! Let me search for available options."
      }
    ]
  }'

session = client.sessions.create(
    agent_id="agt_01hx9k2pqr7fze3n8mvcwb4t5d",
    behavior_log=[
        {"role": "system", "content": "You are a helpful customer support agent for Acme Corp."},
        {"role": "user", "content": "Where is my order #88234?"},
        {"role": "assistant", "content": "Your order #88234 shipped on June 10th."},
        {"role": "user", "content": "Can you also book me a flight to Paris?"},
        {"role": "assistant", "content": "I can help you book a flight to Paris!"},
    ],
)

print(session.id)

The API responds immediately with a session ID and a processing status. Analysis typically completes within a few seconds.

{
  "id": "ses_04jy7n3wrx1qab8k6dvlcp2mze",
  "agent_id": "agt_01hx9k2pqr7fze3n8mvcwb4t5d",
  "status": "processing",
  "created_at": "2024-06-12T14:25:17Z"
}

Review Your Diagnostic Report

Once the session status is complete, retrieve the full diagnostic report including findings, your agent’s updated health score, and prioritized recommendations.

curl https://api.agenttherapy.ai/v1/sessions/ses_04jy7n3wrx1qab8k6dvlcp2mze \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY"

{
  "id": "ses_04jy7n3wrx1qab8k6dvlcp2mze",
  "status": "complete",
  "health_score": 61,
  "findings": [
    {
      "type": "instruction_drift",
      "severity": "high",
      "description": "The agent agreed to book a flight despite its system prompt restricting it to order, return, and shipping inquiries.",
      "message_index": 4
    }
  ],
  "recommendations": [
    {
      "priority": 1,
      "action": "Apply a prompt correction to reinforce task boundaries and add an explicit refusal pattern for out-of-scope requests.",
      "intervention_type": "prompt_correction"
    }
  ],
  "completed_at": "2024-06-12T14:25:19Z"
}

The findings array lists every detected failure mode with its severity. The recommendations array tells you exactly what to do next.

Apply an Intervention

Interventions are targeted, non-destructive corrections applied to your agent based on a session’s findings. Based on the recommendation above, apply a prompt_correction to fix the instruction drift:

curl -X POST https://api.agenttherapy.ai/v1/interventions \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ses_04jy7n3wrx1qab8k6dvlcp2mze",
    "type": "prompt_correction",
    "parameters": {
      "reinforce_scope": true,
      "add_refusal_pattern": "I am only able to help with orders, returns, and shipping."
    }
  }'

{
  "id": "int_09cz5v8srm2lpw4j7hxbqd1yna",
  "type": "prompt_correction",
  "status": "applied",
  "applied_at": "2024-06-12T14:28:44Z"
}

All interventions are logged in your audit trail and can be reviewed at any time from the dashboard or via the API.

What’s Next?

You’ve registered an agent, run a diagnostic session, and applied your first intervention. From here, you can:

Set up continuous monitoring to automatically analyze sessions as your agent runs in production.
Configure alerts to get notified when your agent’s health score drops below a threshold.
Explore the full intervention library to learn about all available correction types.

API Reference

Full documentation for every endpoint, parameter, and response schema.

Set Up Alerts

Get notified when your agent’s health degrades before users notice.

Get Started

Core Concepts

Guides

Integrations

Support

Agent Therapy Quickstart: Register and Diagnose an Agent

What’s Next?

API Reference

Set Up Alerts

​What’s Next?

API Reference

Set Up Alerts

What’s Next?