Agents API

Create, read, update, and delete agents.

List Agents

GET /api/v1/agents

Query Parameters

Parameter	Type	Description
limit	number	Max results (default: 20, max: 100)
offset	number	Pagination offset
tags	string	Comma-separated tags to filter
status	string	Filter by status (active, draft, archived)

Response

{
  "data": [
    {
      "id": "agent_123",
      "name": "Customer Support",
      "content": "You are a helpful...",
      "llmModel": "gpt-4o",
      "description": "Main support chatbot",
      "tags": ["support", "production"],
      "status": "active",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0
  }
}

Get Agent

GET /api/v1/agents/:id

Response

{
  "id": "agent_123",
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "description": "Main support chatbot",
  "tags": ["support", "production"],
  "status": "active",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

Create Agent

POST /api/v1/agents

Request Body

{
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "description": "Main support chatbot",
  "tags": ["support", "production"]
}

Required Fields

Field	Type	Description
name	string	Display name
content	string	System prompt
llmModel	string	Target model (gpt-4o, claude-3.5-sonnet, etc.)

Optional Fields

Field	Type	Description
description	string	What this agent does
tags	string[]	Organization tags
temperature	number	Model temperature (0-2)
maxTokens	number	Max response tokens

Response

{
  "id": "agent_456",
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "status": "active",
  "createdAt": "2025-01-20T14:30:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

Status: 201 Created

Update Agent

PATCH /api/v1/agents/:id

Request Body

{
  "content": "Updated system prompt...",
  "tags": ["support", "v2"]
}

All fields are optional. Only provided fields are updated.

Response

{
  "id": "agent_123",
  "name": "Customer Support",
  "content": "Updated system prompt...",
  "updatedAt": "2025-01-20T15:00:00Z"
}

Delete Agent

DELETE /api/v1/agents/:id

Response

{
  "success": true,
  "message": "Agent deleted"
}

Status: 200 OK

Get Agent Status

GET /api/v1/agents/:id/status

Get agent details including optimization state and performance metrics.

Response

{
  "id": "agent_123",
  "name": "Customer Support",
  "status": "active",
  "optimizationState": "idle",
  "metrics": {
    "conversationCount": 1247,
    "taskCompletionRate": 87.3,
    "avgSentiment": 0.72
  },
  "lastOptimized": "2025-01-18T10:00:00Z"
}

---

Get Agent Insights

GET /api/v1/agents/:id/insights

Get aggregated performance insights for an agent based on conversation data.

Query Parameters

Parameter	Type	Default	Description
days	number	30	Number of days to look back (7, 30, 90, or all)

Response

{
  "agentId": "agent_123",
  "period": {
    "days": 30,
    "from": "2024-12-21T00:00:00Z",
    "to": "2025-01-20T23:59:59Z"
  },
  "summary": {
    "totalConversations": 1247,
    "completedConversations": 1089,
    "abandonedConversations": 158,
    "completionRate": 87.3
  },
  "metrics": {
    "taskCompletion": {
      "rate": 82.5,
      "trend": "+3.2%"
    },
    "sentiment": {
      "average": 0.72,
      "distribution": {
        "positive": 68,
        "neutral": 24,
        "negative": 8
      }
    },
    "avgResponseTime": 1.2,
    "avgConversationLength": 6.4
  },
  "topIssues": [
    {
      "issue": "Unclear refund policy explanation",
      "frequency": 23,
      "impact": "high"
    }
  ],
  "recommendations": [
    "Consider adding specific refund timelines to reduce follow-up questions"
  ]
}

---

Error Responses

Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  }
}

Status: 404 Not Found

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "llmModel": "Must be a valid model name"
    }
  }
}

Status: 400 Bad Request