API ReferenceAgents

Create Task Agent

Create a new Task Agent for the project.

Task Agents orchestrate multiple Tasks as task tools using LLM-powered reasoning.

The request creates the root Task Agent and its initial active revision. Runtime configuration such as instructions, models, and tools is stored on revisions.

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

OR
AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

org_idstringRequiredformat: "uuid"
The organization ID
project_idstringRequiredformat: "uuid"
The project ID

Request

This endpoint expects an object.
namestringRequired<=255 characters
Name of the TaskAgent.
instructionstringRequired

System prompt / instruction for the agent.

llm_model_idstringRequiredformat: "uuid"
ID of the LLM model to use.
descriptionstring or nullOptional
Description of the TaskAgent.
modeenumOptional
Execution mode for the agent.
fallback_llm_model_idstring or nullOptionalformat: "uuid"
Optional fallback LLM model to snapshot for future failover support.
task_toolslist of objectsOptionalDefaults to []

Task tools to add. Order in array determines execution order (index 0 = order 0).

mcp_serverslist of objectsOptionalDefaults to []

MCP servers to attach. Use allowed_tool_ids for tool restriction.

integrationslist of objectsOptionalDefaults to []

Platform integrations to attach. Use allowed_tool_ids for tool restriction.

skillslist of objectsOptionalDefaults to []
Declarative skills to attach. Order in array determines activation precedence.
memory_strategyenum or nullOptional

Memory management strategy. None = unlimited history.

memory_configmap from strings to any or nullOptional

Strategy-specific configuration. Required when memory_strategy is set.

max_turnsinteger or nullOptional1-500

Max conversation turns per session. None = unlimited.

task_agent_run_visibilityenumOptionalDefaults to owner_only
Controls who can see all TaskAgent runs for this agent.

Response

Task Agent created
idstringformat: "uuid"
namestring
task_agent_run_visibilityenum
is_deletedboolean
createdstring
modifiedstring
active_revisionobject or nullOptional
Summary of the active TaskAgent revision.
revisionslist of objectsOptional
shared_with_projectbooleanOptionalDefaults to false

When true the TaskAgent is shared with members of its Project.

seven_day_summaryobject or nullOptional

Optional summary of visible TaskAgent runs created in the last seven days. Populated when the list endpoint is called with seven_day_summary=true.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error