Agents API

Create and manage AI agents programmatically.

:::info Dashboard API Agent CRUD endpoints live on the dashboard API (/api/v1/agents/...) and require a session JWT — the same one your browser uses for the ZenSearch web UI. They are not available on the public /v1/... API key surface. Use these endpoints from server-side code that has obtained a session token via your auth provider, or manage agents through the dashboard UI. :::

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

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

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_current_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);
}

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

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