Skip to navigation
AgentsManagement

Agents · Create an agent

View as Markdown

Creates an agent from a title, model and system prompt. Returns its record including id and slug.

Keep the prompt to the agent’s role and constraints. Detailed behaviour is better attached as a skill than packed into prompt text — skills are separately readable, editable and replaceable.

resource: agent://build-guide covers the build sequence.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
titlestringOptional
Display name, e.g. "Weekly Report Writer".
descriptionstringOptional
One line on what the agent is for. Shown in pickers.
modelstringOptional

Provider-qualified model, e.g. openai:gpt-4o-mini. Omit to take the platform default rather than guessing a string.

system_promptstringOptional

The agent's standing instructions. Durable behaviour belongs in skills instead — they are editable independently and do not require rewriting the prompt.

user_promptstringOptional
Optional template applied to each incoming message.
temperaturedoubleOptional
Sampling temperature. Defaults to 0.7.
statusenumOptional

draft until you are ready. Only active agents can be run, so a trigger on a draft agent fires and fails.

Allowed values:
toolslist of stringsOptional

Built-in tool slugs. Write-only convenience — replaces the whole set, it does not append.

extramap from strings to anyOptional

Agent-level flags. allow_skill_override is the one that matters: without it, built-in skills cannot be edited.

Response

The created agent, including its id and generated slug.

Errors

400
Bad Request Error