Sign in

v1

latestOpenAPI 3.0.02026-07-26492143.5 KB
Agents

Create agent

Create a new agent. The authenticated caller must have permission to create agents on the target team.

post/agents

Request body

namestring required

Display name for the agent.

model_namestring required

ID of the LLM the agent runs on. Use GET /models to discover valid values.

descriptionstring nullable
system_promptstring nullable
toolsobject[]

Tools the agent can call. Each tool is an object whose shape depends on the tool type.

resourcesobject[]

Resources attached to the agent.

skill_idsstring[] nullable

IDs of skills to attach to the agent. Attachment happens inside the create transaction, so an invalid ID fails the whole request (no orphaned agent). Omit to attach none. The caller must hold INVOKE on each skill. After creation, manage skills with PATCH /agents/{agent_id}/skills.

metadataobject nullable

Arbitrary key/value metadata stored on the agent.

folder_idstring nullable

ID of the folder to place the agent in.

is_activeboolean

Whether the agent is active. Defaults to true.

agent_idstring nullable

Optional caller-supplied agent ID. When omitted, the server generates one.

team_idstring nullable

ID of the team to create the agent under. When omitted, the agent is owned by the authenticated user.

Example request

{
  "name": "Sales research agent",
  "model_name": "anthropic/claude-sonnet-4",
  "description": "Researches accounts and drafts outreach",
  "system_prompt": "You are a B2B sales research assistant.",
  "skill_ids": [
    "skill_2b9c",
    "skill_7f1a"
  ],
  "folder_id": "folder_91ab",
  "team_id": "team_4f8c92ab"
}

Response

Agent created.

Example response

{
  "agent": {
    "id": "abc123DEFghiJKL",
    "name": "Sales research agent",
    "description": "Researches accounts and drafts outreach",
    "team_id": "team_4f8c92ab",
    "is_active": true,
    "model_name": "anthropic/claude-sonnet-4",
    "system_prompt": "You are a B2B sales research assistant.",
    "skill_ids": [
      "skill_2b9c",
      "skill_7f1a"
    ],
    "folder_id": "folder_91ab",
    "created_at": "2026-05-15T14:32:00Z"
  }
}