Agents API

Manage AI agents and their configurations.

List Agents

GET /api/agents

Query Parameters:

Parameter	Type	Description
`companyId`	string	Filter by company
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

Response:

{
  "success": true,
  "data": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "industry": "saas",
      "companyId": "company_xyz",
      "metrics": {
        "successRate": 0.85,
        "avgLatency": 1200,
        "totalTraces": 15000
      },
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "hasMore": false
  }
}

Get Agent

GET /api/agents/:id

Path Parameters:

Parameter	Type	Description
`id`	string	Agent ID

Response:

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries",
    "industry": "saas",
    "companyId": "company_xyz",
    "config": {
      "primaryModel": "gpt-4",
      "fallbackModel": "gpt-3.5-turbo",
      "temperature": 0.7,
      "maxTokens": 2000
    },
    "metrics": {
      "successRate": 0.85,
      "avgLatency": 1200,
      "totalTraces": 15000,
      "ragScores": {
        "groundedness": 0.78,
        "faithfulness": 0.82
      }
    },
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-20T14:30:00Z"
  }
}

Create Agent

POST /api/agents

Request Body:

{
  "name": "Sales Assistant",
  "description": "Helps with product inquiries",
  "industry": "ecommerce",
  "companyId": "company_xyz",
  "config": {
    "primaryModel": "gpt-4",
    "temperature": 0.7
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "agent_new123",
    "name": "Sales Assistant",
    "description": "Helps with product inquiries",
    "industry": "ecommerce",
    "companyId": "company_xyz",
    "config": {
      "primaryModel": "gpt-4",
      "temperature": 0.7
    },
    "metrics": {
      "successRate": null,
      "avgLatency": null,
      "totalTraces": 0
    },
    "createdAt": "2024-01-21T10:00:00Z",
    "updatedAt": "2024-01-21T10:00:00Z"
  }
}

Update Agent

PATCH /api/agents/:id

Request Body:

{
  "name": "Updated Agent Name",
  "config": {
    "temperature": 0.5
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Updated Agent Name",
    ...
  }
}

Delete Agent

DELETE /api/agents/:id

Response:

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

⚠️

Deleting an agent does not delete associated traces. Use the data retention settings to manage trace cleanup.

Agent Configuration

The config object supports:

Field	Type	Description
`primaryModel`	string	Primary LLM model
`fallbackModel`	string	Fallback model for failures
`temperature`	number	Generation temperature (0-2)
`maxTokens`	number	Max tokens per response
`systemPrompt`	string	Default system prompt
`retrievalConfig`	object	Vector search settings

Industry Types

Industry	Description
`saas`	Software as a Service
`ecommerce`	E-commerce
`fintech`	Financial Technology
`healthcare`	Healthcare & Medical
`support`	Customer Support
`education`	Education & Learning
`other`	Other industries

Departments

Organize agents into departments for team-level management.

List Departments

GET /api/departments

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 20)

Response:

{
  "success": true,
  "data": [
    {
      "id": "dept_001",
      "name": "Customer Support",
      "description": "All customer-facing support agents",
      "agentCount": 12,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Create Department

POST /api/departments

Request Body:

{
  "name": "Customer Support",
  "description": "All customer-facing support agents"
}

Response (201):

{
  "success": true,
  "data": {
    "id": "dept_001",
    "name": "Customer Support",
    "description": "All customer-facing support agents",
    "agentCount": 0,
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Update Department

PATCH /api/departments/:id

Path Parameters:

Parameter	Type	Description
`id`	string	Department ID

Request Body:

{
  "name": "Updated Name",
  "description": "Updated description"
}

Delete Department

DELETE /api/departments/:id

Path Parameters:

Parameter	Type	Description
`id`	string	Department ID

Agent Config

Manage detailed agent configurations separately from the agent record.

Get Agent Config

GET /api/agent-configs/:agentId

Path Parameters:

Parameter	Type	Description
`agentId`	string	Agent ID

Response:

{
  "success": true,
  "data": {
    "agentId": "agent_abc123",
    "systemPrompt": "You are a helpful support agent...",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 2048,
    "tools": ["search", "ticket_lookup"],
    "updatedAt": "2025-01-15T10:00:00Z"
  }
}

Create Agent Config

POST /api/agent-configs

Request Body:

{
  "agentId": "agent_abc123",
  "systemPrompt": "You are a helpful support agent...",
  "model": "gpt-4",
  "temperature": 0.7,
  "maxTokens": 2048,
  "tools": ["search", "ticket_lookup"]
}

Update Agent Config

PUT /api/agent-configs/:agentId

Path Parameters:

Parameter	Type	Description
`agentId`	string	Agent ID

Request Body: Same fields as Create (all optional for update).

Delete Agent Config

DELETE /api/agent-configs/:agentId

Path Parameters:

Parameter	Type	Description
`agentId`	string	Agent ID

Next Steps

Traces — Trace ingestion and querying
Issues & Fixes — Failure management
Evaluation & Grading — Quality evaluation

Authentication & API Keys Traces & Spans