Skip to main content

Agents API

Create and manage AI agents programmatically.

List Agents​

Endpoint​

GET /api/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 /api/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​

ParameterTypeRequiredDescription
namestringYesAgent name
descriptionstringNoAgent description
systemPromptstringYesSystem instructions
toolsstring[]NoEnabled tools
collectionsstring[]NoAccessible collections
startMessagestringNoInitial 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 /api/v1/agents/{id}

Update Agent​

Endpoint​

PUT /api/v1/agents/{id}

Request Body​

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

Delete Agent​

Endpoint​

DELETE /api/v1/agents/{id}

Execute Agent​

Endpoint​

POST /api/v1/agents/{id}/execute/stream

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​

ToolDescription
search_documentsSearch across collections
get_documentRetrieve full document
summarize_documentGenerate summary
search_database_schemaDiscover DB schema
query_databaseExecute SQL query
get_table_infoGet table details
calculatePerform calculations
get_datetimeGet 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);
}

Agent Templates​

Agent templates are reusable blueprints for creating agents.

List Templates​

GET /api/v1/agent-templates

Get Template​

GET /api/v1/agent-templates/{id}

Create Agent from Template​

POST /api/v1/agents/from-template/{templateId}

Agent Memory​

Agents can store persistent memories (facts, preferences, insights, procedures) across conversations.

Create Memory​

POST /api/v1/agents/{id}/memories

List Memories​

GET /api/v1/agents/{id}/memories

Get Memory​

GET /api/v1/agents/{id}/memories/{memoryId}

Update Memory​

PUT /api/v1/agents/{id}/memories/{memoryId}

Delete Memory​

DELETE /api/v1/agents/{id}/memories/{memoryId}

Search Memories​

GET /api/v1/agents/{id}/memories/search

Next Steps​