API Reference
Agents API
API endpoints for managing agents.
List Agents
GET /agentsQuery Parameters:
| Param | Type | Description |
|---|---|---|
creation_method | string | Optional filter by creation method |
Response: 200 - AgentResponse[]
Create Agent
POST /agentsRequest Body:
{
"name": "Content Marketing Strategist",
"domain": "marketing",
"description": "Generates content strategies for B2B SaaS",
"objective": "Create data-driven content plans"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Agent name |
domain | string | No | Domain (default: "general") |
description | string | No | Agent description |
objective | string | No | Agent objective |
system_prompt | string | No | System prompt |
Response: 201 - AgentResponse
Build Agent from Description
POST /agents/buildCreate an agent from a natural language description. Kate extracts name, domain, objective, and configuration.
Request Body:
{
"prompt": "I need an agent that helps freelancers optimize their tax situation, focused on US self-employment tax"
}Response: 201 - AgentBuildResponse (includes extracted configuration)
Get Agent
GET /agents/{agent_id}Response: 200 - AgentResponse
Update Agent
PATCH /agents/{agent_id}Request Body: Any subset of name, domain, description, objective, system_prompt.
Response: 200 - AgentResponse
Delete Agent
DELETE /agents/{agent_id}Response: 200 - {"detail": "Agent deleted"}
Refresh Agent Scores
GET /agents/{agent_id}/refreshGet fresh evaluation scores.
Response: 200
{
"score": 0.78,
"auto_eval_score": 0.82,
"avg_user_rating": null,
"latest_run": { ... }
}SDK Equivalent
agents = await client.agents.list()
agent = await client.agents.create(name="My Agent", domain="general")
agent = await client.agents.get(agent_id="...")
agent = await client.agents.update(agent_id="...", name="New Name")
await client.agents.delete(agent_id="...")