Skip to main content
POST
/
api
/
v1
/
agent
/
{id}
/
subagents
Create Sub-Agent
curl --request POST \
  --url https://api.example.com/api/v1/agent/{id}/subagents
Runtime agent creation is exposed as sub-agent creation under an existing parent agent.

​
Path Parameters

ParameterTypeDescription
idstringParent agent ID

​
Request Body

{
  "name": "SupportAgent",
  "description": "Escalated support specialist",
  "system_prompt": "You are a customer support specialist.",
  "llm_config": {
    "model": "openai/gpt-5.4-mini",
    "temperature": 1.0,
    "max_tokens": 4000
  },
  "enable_planning": true,
  "enable_reflection": false,
  "knowledge_bases": ["550e8400-e29b-41d4-a716-446655440000"],
  "tool_assignments": ["lookup_ticket"]
}
FieldTypeRequiredDescription
namestringyesSub-agent name
descriptionstringyesSub-agent description
system_promptstringnoCustom instructions for the sub-agent
llm_configobjectnoModel configuration override
enable_planningbooleannoEnable planning for this sub-agent
enable_reflectionbooleannoEnable reflection for this sub-agent
knowledge_basesstring[]noKB IDs assigned to the sub-agent
tool_assignmentsstring[]noTool names to store as sub-agent assignments on create/update
Use KB IDs in knowledge_bases. The create/update tool_assignments field stores tool names. The dedicated assign/remove endpoints under /api/v1/agent/{id}/subagents/{subagent_id}/tools use a tool UUID as tool_identifier.

​
Response

Returns the created sub-agent configuration with its generated ID. 
{
  "id": "agent_support_123",
  "name": "SupportAgent",
  "description": "Escalated support specialist",
  "icon": "users",
  "icon_type": "heroicon",
  "icon_url": null,
  "icon_display": "users",
  "icon_color": null,
  "is_system_agent": false,
  "implementation_type": "user",
  "created_by_user_id": "auth0|user_123",
  "tool_count": 0,
  "enable_planning": true,
  "enable_reflection": false,
  "tool_assignments": ["lookup_ticket"],
  "knowledge_bases": ["550e8400-e29b-41d4-a716-446655440000"],
  "created_at": "2026-04-28T14:30:00",
  "updated_at": "2026-04-28T14:30:00"
}