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

# Agent Therapy Quickstart: Register and Diagnose an Agent

> Register your first AI agent, submit a behavior log, and receive a diagnostic report with a health score and fix recommendations in under 5 minutes.

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.

**1. Sign Up & Get Your API Key**

If you haven't already, [create your Agent Therapy account](https://app.agenttherapy.ai/signup). Once you're in the dashboard:

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

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

```bash theme={null}
export AGENT_THERAPY_API_KEY="at_live_xxxxxxxxxxxxxxxxxxxx"
```

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

**2. Register Your Agent**

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.

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

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

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

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

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

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

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

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

```bash theme={null}
curl https://api.agenttherapy.ai/v1/sessions/ses_04jy7n3wrx1qab8k6dvlcp2mze \
  -H "Authorization: Bearer $AGENT_THERAPY_API_KEY"
```

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

**5. 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:

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

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

> [!NOTE]
>
> 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](https://vizmaxxing.com/api/overview.md)**
>
> Full documentation for every endpoint, parameter, and response schema.

> **[Set Up Alerts](https://vizmaxxing.com/guides/setting-up-alerts.md)**
>
> Get notified when your agent's health degrades before users notice.


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