API ReferenceTask Agents

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

Bearer token authentication using JWT tokens from Ory Kratos/Hydra

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 objectsOptional

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

mcp_serverslist of objectsOptional

MCP servers to attach. Use allowed_tool_ids for tool restriction.

integrationslist of objectsOptional

Platform integrations to attach. Use allowed_tool_ids for tool restriction.

skillslist of objectsOptional
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 null
Summary of the active TaskAgent revision.
revisionslist of objects

Errors

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