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

# Agents REST API: Register and Manage Your AI Agents

> Full reference for the Agent Therapy Agents API — create, retrieve, update, list, and delete the AI agent records you monitor for behavioral health.

The Agents resource represents an AI agent you have registered with Agent Therapy for behavioral monitoring. Each agent record holds descriptive metadata, its current health score (a rolling average calculated from recent diagnostic sessions), and links to all sessions run against it. You must register an agent before you can submit sessions or diagnostics for it.

***

## POST /agents

Register a new agent with Agent Therapy. Once registered, the agent receives a unique `id` that you use when submitting sessions and diagnostics.

### Request Body

**name** `string` *required*

A human-readable name for the agent. Must be between 1 and 128 characters.

**description** `string`

An optional free-text description of the agent's purpose, architecture, or deployment context.

**framework** `string`

The AI framework the agent is built on. Accepted values: `openai`, `langchain`, `autogen`, `custom`. Defaults to `custom` if omitted.

**tags** `array`

An optional array of string tags for organizing and filtering agents. For example, `["production", "support", "gpt-4o"]`.

### Response Fields

**id** `string`

The unique identifier for the agent. Prefixed with `agt_`.

**name** `string`

The name you provided at registration.

**framework** `string`

The framework value set at registration.

**description** `string`

The description value set at registration, or `null` if not provided.

**tags** `array`

The array of tags assigned to the agent.

**health\_score** `null`

Always `null` at creation. Populated after the first completed diagnostic session.

**status** `string`

The agent's current status. Set to `active` at creation.

**created\_at** `string`

ISO 8601 timestamp indicating when the agent was registered.

### Example

```bash theme={null}
curl -X POST https://api.agenttherapy.ai/v1/agents \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot v2",
    "description": "Customer-facing support agent handling tier-1 tickets.",
    "framework": "langchain",
    "tags": ["production", "support", "gpt-4o"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "agt_01j9z3kx2m4n8p7q",
    "name": "Support Bot v2",
    "framework": "langchain",
    "description": "Customer-facing support agent handling tier-1 tickets.",
    "tags": ["production", "support", "gpt-4o"],
    "health_score": null,
    "status": "active",
    "created_at": "2024-11-14T09:22:05Z"
  }
}
```

***

## GET /agents

List all agents registered to your account. Results are paginated and can be filtered by framework or status.

### Query Parameters

**limit** `integer`

Number of agents to return per page. Defaults to `20`, maximum `100`.

**cursor** `string`

Cursor from the previous page's `next_cursor` field. Omit for the first request.

**framework** `string`

Filter results to agents built on a specific framework. Accepted values: `openai`, `langchain`, `autogen`, `custom`.

**status** `string`

Filter results by agent status. Accepted values: `active`, `archived`.

### Example

```bash theme={null}
curl "https://api.agenttherapy.ai/v1/agents?framework=langchain&limit=10" \
  -H "Authorization: Bearer at_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "id": "agt_01j9z3kx2m4n8p7q",
      "name": "Support Bot v2",
      "framework": "langchain",
      "health_score": 84,
      "status": "active",
      "created_at": "2024-11-14T09:22:05Z"
    },
    {
      "id": "agt_02k8y4lw3n5o9r6s",
      "name": "Sales Assistant",
      "framework": "langchain",
      "health_score": 91,
      "status": "active",
      "created_at": "2024-11-10T14:05:33Z"
    }
  ],
  "next_cursor": "cur_03l7x5mv4o6p0s7t",
  "has_more": true
}
```

***

## GET /agents/{id}

Retrieve a single agent by its unique ID, including its current health score, total session count, and the timestamp of its most recent session.

### Path Parameters

**id** `string` *required*

The unique identifier of the agent to retrieve. Prefixed with `agt_`.

### Response Fields

**id** `string`

The agent's unique identifier.

**name** `string`

The agent's display name.

**framework** `string`

The AI framework the agent is built on.

**description** `string`

The agent's description.

**tags** `array`

Tags assigned to the agent.

**health\_score** `number`

The current rolling health score (0–100), calculated as a weighted average over the agent's most recent sessions. Returns `null` if no sessions have been completed.

**status** `string`

The agent's current status: `active` or `archived`.

**sessions\_count** `integer`

The total number of diagnostic sessions run against this agent.

**last\_session\_at** `string`

ISO 8601 timestamp of the most recently completed session, or `null` if no sessions exist.

**created\_at** `string`

ISO 8601 timestamp indicating when the agent was registered.

### Example

```bash theme={null}
curl https://api.agenttherapy.ai/v1/agents/agt_01j9z3kx2m4n8p7q \
  -H "Authorization: Bearer at_your_key_here"
```

```json theme={null}
{
  "data": {
    "id": "agt_01j9z3kx2m4n8p7q",
    "name": "Support Bot v2",
    "framework": "langchain",
    "description": "Customer-facing support agent handling tier-1 tickets.",
    "tags": ["production", "support", "gpt-4o"],
    "health_score": 84,
    "status": "active",
    "sessions_count": 17,
    "last_session_at": "2024-11-14T11:45:00Z",
    "created_at": "2024-11-14T09:22:05Z"
  }
}
```

***

## PATCH /agents/{id}

Update the mutable metadata fields of an existing agent. Only include the fields you want to change — all other fields remain unchanged.

### Path Parameters

**id** `string` *required*

The unique identifier of the agent to update.

### Request Body

**name** `string`

A new display name for the agent.

**description** `string`

A new description for the agent.

**tags** `array`

A new set of string tags. This **replaces** the existing tags array entirely — it does not merge.

### Example

```bash theme={null}
curl -X PATCH https://api.agenttherapy.ai/v1/agents/agt_01j9z3kx2m4n8p7q \
  -H "Authorization: Bearer at_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot v3",
    "tags": ["production", "support", "gpt-4o", "v3"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "agt_01j9z3kx2m4n8p7q",
    "name": "Support Bot v3",
    "framework": "langchain",
    "description": "Customer-facing support agent handling tier-1 tickets.",
    "tags": ["production", "support", "gpt-4o", "v3"],
    "health_score": 84,
    "status": "active",
    "created_at": "2024-11-14T09:22:05Z"
  }
}
```

***

## DELETE /agents/{id}

Delete an agent from Agent Therapy. This permanently removes the agent record and all associated data.

> [!WARNING]
>
> Deleting an agent also **permanently deletes all of its sessions, diagnostic reports, and findings**. This action is irreversible. If you only want to stop monitoring an agent temporarily, consider archiving it via `PATCH /agents/{id}` by setting `status` to `archived` instead.

### Path Parameters

**id** `string` *required*

The unique identifier of the agent to delete.

### Example

```bash theme={null}
curl -X DELETE https://api.agenttherapy.ai/v1/agents/agt_01j9z3kx2m4n8p7q \
  -H "Authorization: Bearer at_your_key_here"
```

A successful delete returns an HTTP `204 No Content` response with no body.


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