Agents API

Create and manage AI agents programmatically.

List Agents

Endpoint

GET /v1/agents

Response

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Research Assistant",
      "description": "Helps with research tasks",
      "tools": ["search_documents", "summarize_document"],
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Agent

Endpoint

POST /v1/agents

Request Body

{
  "name": "Sales Analyst",
  "description": "Analyzes sales data and trends",
  "systemPrompt": "You are a sales analyst...",
  "tools": ["search_documents", "query_database", "calculate"],
  "collections": ["col_sales", "col_crm"]
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	Agent name
description	string	No	Agent description
systemPrompt	string	Yes	System instructions
tools	string[]	No	Enabled tools
collections	string[]	No	Accessible collections
startMessage	string	No	Initial greeting

Response

{
  "data": {
    "id": "agent_xyz789",
    "name": "Sales Analyst",
    "description": "Analyzes sales data and trends",
    "tools": ["search_documents", "query_database", "calculate"],
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Get Agent

Endpoint

GET /v1/agents/{id}

Update Agent

Endpoint

PUT /v1/agents/{id}

Request Body

{
  "name": "Updated Name",
  "tools": ["search_documents"]
}

Delete Agent

Endpoint

DELETE /v1/agents/{id}

Run Agent

Endpoint

POST /v1/agents/{id}/run

Request Body

{
  "message": "Analyze Q4 sales trends",
  "conversationId": "conv_abc123"
}

Response (Streaming)

Uses SSE for real-time updates:

event: run_start
data: {"runId": "run_abc123"}

event: iteration
data: {"number": 1, "status": "planning"}

event: tool_call
data: {"tool": "search_documents", "params": {...}}

event: tool_result
data: {"tool": "search_documents", "success": true}

event: content
data: {"content": "Based on my analysis..."}

event: run_complete
data: {"usage": {"totalTokens": 1500}}

Available Tools

Tool	Description
search_documents	Search across collections
get_document	Retrieve full document
summarize_document	Generate summary
search_database_schema	Discover DB schema
query_database	Execute SQL query
get_table_info	Get table details
calculate	Perform calculations
get_datetime	Get current time

Example Usage

Create Agent

const agent = await client.agents.create({
  name: 'Research Assistant',
  systemPrompt: 'You are a helpful research assistant...',
  tools: ['search_documents', 'summarize_document']
});

Run Agent

const stream = await client.agents.run(agent.id, {
  message: 'Summarize recent product updates'
});

for await (const event of stream) {
  console.log(event);
}

Next Steps

• Chat API - Use agents in chat
• Documents API - Document operations