Agents REST API: Register and Manage Your AI Agents

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

string

required

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

string

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

string

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

array

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

Response Fields

string

The unique identifier for the agent. Prefixed with agt_.

string

The name you provided at registration.

string

The framework value set at registration.

string

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

array

The array of tags assigned to the agent.

null

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

string

The agent’s current status. Set to active at creation.

string

ISO 8601 timestamp indicating when the agent was registered.

Example

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

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

integer

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

string

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

string

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

string

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

Example

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

{
  "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/

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

string

required

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

Response Fields

string

The agent’s unique identifier.

string

The agent’s display name.

string

The AI framework the agent is built on.

string

The agent’s description.

array

Tags assigned to the agent.

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.

string

The agent’s current status: active or archived.

integer

The total number of diagnostic sessions run against this agent.

string

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

string

ISO 8601 timestamp indicating when the agent was registered.

Example

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

{
  "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/

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

Path Parameters

string

required

The unique identifier of the agent to update.

Request Body

string

A new display name for the agent.

string

A new description for the agent.

array

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

Example

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

{
  "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/

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

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

string

required

The unique identifier of the agent to delete.

Example

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.

Overview

Endpoints

Webhooks

Agents REST API: Register and Manage Your AI Agents

POST /agents

Request Body

Response Fields

Example

GET /agents

Query Parameters

Example

GET /agents/

Path Parameters

Response Fields

Example

PATCH /agents/

Path Parameters

Request Body

Example

DELETE /agents/

Path Parameters

Example

​POST /agents

​Request Body

​Response Fields

​Example

​GET /agents

​Query Parameters

​Example

​GET /agents/

​Path Parameters

​Response Fields

​Example

​PATCH /agents/

​Path Parameters

​Request Body

​Example

​DELETE /agents/

​Path Parameters

​Example

POST /agents

Request Body

Response Fields

Example

GET /agents

Query Parameters

Example

GET /agents/

Path Parameters

Response Fields

Example

PATCH /agents/

Path Parameters

Request Body

Example

DELETE /agents/

Path Parameters

Example