The Agents API allows you to create, configure, and manage named AI agents backed by skill files. Each agent has a custom system prompt, model settings, and optional skills.
List Agents curl -X GET "http://localhost:8000/api/agents" \ -H "Authorization: Bearer YOUR_TOKEN"
{ "agents" : [ { "id" : "researcher" , "name" : "Researcher" , "description" : "Deep research and analysis specialist" , "emoji" : "🔍" , "icon" : "" , "avatar" : "" , "category" : "research" , "model" : "claude-sonnet-4" , "thinking" : "extended" , "skills" : [ "web-search" , "rag" ], "system_prompt" : "You are a meticulous researcher..." , "enabled" : true , "knowledge_path" : "/workspace/skills/researcher/knowledge" } ] }
Endpoint List all named agents with optional filtering.
Query Parameters Search query (matches id, name, or description)
Only return enabled agents
Only return disabled agents
Response Array of agent definitions Unique agent identifier (slug)
Preferred model (e.g., claude-sonnet-4)
Thinking mode (e.g., extended, fast)
Enabled skill IDs (e.g., ["web-search", "rag"])
Whether the agent is active
Path to agent’s knowledge directory
Create Agent curl -X POST "http://localhost:8000/api/agents" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Researcher", "description": "Deep research and analysis specialist", "emoji": "🔍", "category": "research", "model": "claude-sonnet-4", "thinking": "extended", "skills": ["web-search", "rag"], "system_prompt": "You are a meticulous researcher who excels at finding and analyzing information. Always cite sources and provide comprehensive analysis." }'
{ "agent" : { "id" : "researcher" , "name" : "Researcher" , "description" : "Deep research and analysis specialist" , "emoji" : "🔍" , "icon" : "" , "avatar" : "" , "category" : "research" , "model" : "claude-sonnet-4" , "thinking" : "extended" , "skills" : [ "web-search" , "rag" ], "system_prompt" : "You are a meticulous researcher..." , "enabled" : true , "knowledge_path" : "/workspace/skills/researcher/knowledge" } }
Endpoint Create a new named agent.
Request Body Agent name (will be slugified to create ID)
Icon identifier (alternative to emoji)
Agent category (e.g., “research”, “coding”)
Preferred model (e.g., claude-sonnet-4)
Thinking mode (e.g., extended, fast)
Array of skill IDs to enable (e.g., ["web-search", "rag"])
Custom system prompt defining agent behavior
Response Created agent object (same structure as list response)
Get Agent curl -X GET "http://localhost:8000/api/agents/researcher" \ -H "Authorization: Bearer YOUR_TOKEN"
{ "agent" : { "id" : "researcher" , "name" : "Researcher" , "description" : "Deep research and analysis specialist" , "emoji" : "🔍" , "model" : "claude-sonnet-4" , "thinking" : "extended" , "skills" : [ "web-search" , "rag" ], "system_prompt" : "You are a meticulous researcher..." , "enabled" : true , "knowledge_path" : "/workspace/skills/researcher/knowledge" } }
Endpoint GET /api/agents/{agent_id}
Get a single agent by ID.
Path Parameters Update Agent curl -X PATCH "http://localhost:8000/api/agents/researcher" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "Enhanced research specialist with web search", "skills": ["web-search", "rag", "arxiv"] }'
{ "agent" : { "id" : "researcher" , "name" : "Researcher" , "description" : "Enhanced research specialist with web search" , "emoji" : "🔍" , "model" : "claude-sonnet-4" , "thinking" : "extended" , "skills" : [ "web-search" , "rag" , "arxiv" ], "system_prompt" : "You are a meticulous researcher..." , "enabled" : true , "knowledge_path" : "/workspace/skills/researcher/knowledge" } }
Endpoint PATCH /api/agents/{agent_id}
Update an existing agent. All fields are optional.
Path Parameters Request Body (all fields optional) New skills array (replaces existing)
Toggle Agent Status cURL (Enable)
cURL (Disable)
curl -X PUT "http://localhost:8000/api/agents/researcher/enabled" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"enabled": true}'
{ "agent" : { "id" : "researcher" , "name" : "Researcher" , "description" : "Deep research and analysis specialist" , "enabled" : true , "..." : "..." } }
Endpoint PUT /api/agents/{agent_id}/enabled
Enable or disable an agent (marketplace-style toggle).
Path Parameters Request Body Whether to enable (true) or disable (false) the agent
Delete Agent curl -X DELETE "http://localhost:8000/api/agents/researcher" \ -H "Authorization: Bearer YOUR_TOKEN"
{ "ok" : true , "deleted" : "researcher" }
Endpoint DELETE /api/agents/{agent_id}
Permanently delete an agent and its skill folder.
Path Parameters Scaffold Agent Knowledge curl -X POST "http://localhost:8000/api/agents/researcher/knowledge/scaffold" \ -H "Authorization: Bearer YOUR_TOKEN"
{ "ok" : true , "agent_id" : "researcher" , "knowledge_path" : "/workspace/skills/researcher/knowledge" }
Endpoint POST /api/agents/{agent_id}/knowledge/scaffold
Ensure local knowledge folders exist for the agent.
Path Parameters Agent Mentions Agents can be invoked in messages using the @Agent Name: message syntax:
@Researcher: Find recent papers on transformer architectures
The API automatically:
Parses the @Agent Name: prefix
Resolves the agent by name or ID
Applies the agent’s system prompt and settings
Executes the message with agent context
Only enabled agents can be invoked via mentions.
Skill Integration Agents can use bundled skills by specifying them in the skills array:
{ "skills" : [ "web-search" , "rag" , "arxiv" , "calculator" ] }
Skills are normalized to lowercase with hyphens and stored in JSON format in the agent’s SKILL.md frontmatter.