--- title: "Create an agent" method: POST path: "/agents" tags: ["Agents"] --- # Create an agent `POST /agents` ## Request - Base URL: `https://api.axilio.ai/api/v1` - URL: `https://api.axilio.ai/api/v1/agents` - Auth: API key in header `X-Axilio-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates an agent: a task for a phone, as instructions an agent works through a model or as code, with the model, output schema and limits its runs use. Sending instructions or code creates the agent's first revision with it; sending source_run_id saves one of your agent runs as the agent, its task or its script as the first revision. A name already used in the organization is 409; an unsupported model, an invalid output schema, both instructions and code, or a run with no task or script to save is 400; another organization's run is 404. ## Request body - AgentCreateRequest: Request body for creating an agent. With instructions, code or source_run_id, the agent's first revision is created with it. - `accessibility_enabled` boolean: Use accessibility mode for runs (default false). Needs your organization's access to accessibility mode: without it the create is refused with a 403 whose message starts with accessibility_unavailable. - `capture_enabled` boolean: Capture the media runs produce into the file library (default true). - `code` string: Python the agent runs. Creates a code revision. Leave out to add a revision later, or send instructions instead. - `from` 'task' | 'script': With source_run_id, what the first revision is. task (default): the run's task, as an instructions revision. script: the script the run left (GET /runs/{run_id}/script), as a code revision. A run with no task, or no script, is 400. - `instructions` string: The task for the agent to work through a model. Creates an instructions revision. Leave out to add a revision later, or send code instead. - `max_cost_microdollars` integer: Most a run's model steps may cost, in microdollars (default 10000000). - `max_steps` integer: Most model steps a run may take (default 500). - `model` string: The model instruction runs call, one of GET /models. Defaults to the platform default. - `name` string, required: The agent's name: letters, numbers, hyphens and underscores, unique within the organization. - `on_failure` 'fail' | 'ask' | 'repair': With code: what a run does when a step fails. fail (default) fails the run. ask pauses the run for a person (reason step_check_failed), who retries the step or completes the run with its output. repair hands the run to the agent, which finishes the task from the live screen and proposes a fixed revision for a person to promote. - `output_schema` object: The JSON Schema a run's result must satisfy. Leave out to take any result. - `pause_timeout_seconds` integer: Longest a run waits paused for an answer, in seconds (default 600, 60 to 3600). - `recording_enabled` boolean: Record the screen of runs (default false). - `source_run_id` string, uuid: Save one of your agent runs as the agent: its first revision comes from the run (see from), and the run's model, output schema and limits stand in for any left out here. Send it without instructions or code. Another organization's run is 404. - `telemetry_enabled` boolean: Emit telemetry for runs (default true). - `timeout_seconds` integer: Longest a run may take, in seconds (default 3600, at most 3600). ## Response `201` Created - Agent: An agent: a task for a phone, as instructions the agent works through a model or as code, with the settings its runs use. - `accessibility_enabled` boolean, required: Runs use accessibility mode, which needs a phone that supports it. - `capture_enabled` boolean, required: Runs capture the media they produce on the phone into the file library. - `created_at` string, date-time, required: When the agent was created. - `current_revision_id` string, uuid: The revision runs of the agent use. Absent until the agent has one. - `id` string, uuid, required: The agent's id. - `last_run_at` string, date-time: When a run of the agent last started. - `max_cost_microdollars` integer, required: Most a run's model steps may cost, in microdollars. - `max_steps` integer, required: Most model steps a run may take. - `model` string, required: The model an instructions revision's runs call, one of GET /models. - `name` string, required: The agent's name, unique within the organization. - `output_schema` object: The JSON Schema a run's result must satisfy. Absent takes any result. - `pause_timeout_seconds` integer, required: Longest a run waits paused for an answer, in seconds, before it fails with input_timeout. A pause also ends with the session. - `recording_enabled` boolean, required: Runs record the screen. - `telemetry_enabled` boolean, required: Runs emit telemetry, live and stored. - `timeout_seconds` integer, required: Longest a run may take, in seconds, within the one-hour session cap. - `updated_at` string, date-time, required: When the agent was last changed. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `422`: Unprocessable Entity - `500`: Internal Server Error ## Changes - **2026-11-02** `62aa324803a7`: 1 info - endpoint added [Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/agents/post.md) --- [API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)