---
title: "Create an agent"
method: POST
path: "/v1/agents"
tags: ["Agents"]
---

# Create an agent

`POST /v1/agents`

## Request

- Base URL: `https://api.dexto.ai`
- URL: `https://api.dexto.ai/v1/agents`
- Auth: HTTP bearer

Create an agent. Each agent starts at version 1; its tools are the only tools its runs get.

## Request body

- object
  - `description` string, nullable: Optional description for your own reference.
  - `instructions` string, required: The agent's system instructions.
  - `model` string, nullable: A model id from GET /v1/models. Leave null to use your plan's model.
  - `name` string, required: Display name.
  - `tools` union[]: Every tool the agent may use. Runs get nothing else.
    - union
      - object
        - `require_approval` boolean: Pause the run for an approval before each search.
        - `type` 'web_search', required: Searches the web.
      - object
        - `require_approval` boolean: Pause the run for an approval before each fetch.
        - `type` 'web_fetch', required: Reads the text of web pages by URL, up to 10 per call.
      - object
        - `prefix` string: Only files whose path starts with this, ending in "/" (such as knowledge/). Empty reaches every file of the project.
        - `read_only` boolean: Give the agent only read_file, read_media_file, glob_files and search_files.
        - `require_approval` boolean: Pause the run for an approval before each write_file, edit_file, delete_file and share_file call. Reads never ask.
        - `type` 'files', required: Gives the agent file tools on this API key's Cloud project's files under the prefix, which the agent sees as /: read_file, read_media_file, write_file, edit_file, glob_files, search_files, delete_file and share_file. Stored bytes are charged to the project.
      - object
        - `deployment_id` string, uuid, required: The ready Function deployment to call.
        - `name` string, required: Lowercase tool name. Each operation becomes the model tool <name>_<operation>.
        - `operations` string[], required: Published operations the agent may call.
        - `project_id` string, uuid, required: A Function you own in this organization.
        - `require_approval` boolean: Pause the run for an approval before each call.
        - `type` 'function', required: Calls operations of your own Function.
      - object
        - `require_approval` boolean: Pause the run for an approval before each sandbox call.
        - `sandbox` union, required: Which sandbox the agent works in.
          - object
            - `sandbox_id` string, uuid, required: A sandbox in this API key's Cloud project.
            - `type` 'project', required: Every run shares this sandbox.
          - object
            - `size` 'large', required
            - `type` 'session', required: Each session gets its own sandbox, created on first use and deleted when the session ends: its agent is archived, or it has had no run for 24 hours.
        - `secrets` string[]: Names of this key's Cloud project's secrets the agent's commands may use. Each command sees the name as an environment variable holding a placeholder, and Dexto attaches the real value to HTTPS requests to that secret's hosts. At most one secret per host.
        - `type` 'sandbox', required: Starts and pauses a sandbox, works with its files and runs commands in it. Its compute is paid from credits.
      - object
        - `auth` object, nullable: The server's credential; null for a server that needs none.
          - `secret` string, required: A secret of this key's Cloud project whose hosts include the server's host. Dexto sends it with each request as the secret's placement says.
          - `type` 'secret', required
        - `name` string, required: Lowercase tool name. Each MCP tool becomes the model tool <name>_<tool>.
        - `require_approval` boolean: Pause the run for an approval before each call.
        - `server_url` string, uri, required: The server's Streamable HTTP MCP endpoint: HTTPS on a public host.
        - `tools` string[], required: Tools of the server the agent may call. Dexto lists the server's tools when the agent is saved, refuses names it does not publish and keeps their input schemas with the version.
        - `type` 'mcp', required: Calls tools of a remote MCP server from Dexto's servers, with the credential attached by Dexto. Each call is paid from credits.
      - object
        - `kinds` string[]: The media the agent may generate. Omit to allow all three.
        - `require_approval` boolean: Pause the run for an approval before each generation.
        - `type` 'media', required: Lists media models, estimates and generates images, audio or video. Each generation is paid from credits. With a files tool, a generation can save its outputs as project files under that tool's prefix.
      - object
        - `max_active` integer: The most active automations the agent may have created at once.
        - `require_approval` boolean: Pause the run for an approval before each create and resume.
        - `type` 'automations', required: Lets the agent schedule follow-ups for itself: create, list, pause, resume and delete schedule automations that run it again in this session or a new one. Each firing is a run paid from credits.

## Response `201`

Created.

- object
  - `archived_at` string, date-time, nullable, required
  - `cloud_project` object, required: The Cloud project that owns the agent: the creating key's project.
    - `id` string, uuid, required
    - `name` string, required
  - `created_at` string, date-time, required
  - `description` string, nullable, required
  - `id` string, uuid, required
  - `instructions` string, required
  - `model` string, nullable, required
  - `name` string, required
  - `object` 'agent', required
  - `tools` union[], required
    - union
      - object
        - `require_approval` boolean, required
        - `type` 'web_search', required
      - object
        - `require_approval` boolean, required
        - `type` 'web_fetch', required
      - object
        - `prefix` string, required
        - `read_only` boolean, required
        - `require_approval` boolean, required
        - `type` 'files', required
      - object
        - `deployment_id` string, uuid, required
        - `name` string, required
        - `operations` string[], required
        - `project_id` string, uuid, required
        - `require_approval` boolean, required
        - `type` 'function', required
      - object
        - `require_approval` boolean, required
        - `sandbox` union, required
          - object
            - `sandbox_id` string, uuid, required
            - `type` 'project', required
          - object
            - `size` 'small' | 'large', required
            - `type` 'session', required
        - `secrets` string[], required
        - `type` 'sandbox', required
      - object
        - `auth` object, nullable, required
          - `secret` string, required
          - `type` 'secret', required
        - `name` string, required
        - `require_approval` boolean, required
        - `server_url` string, required
        - `tools` string[], required
        - `type` 'mcp', required
      - object
        - `kinds` string[], required
        - `require_approval` boolean, required
        - `type` 'media', required
      - object
        - `max_active` integer, required
        - `require_approval` boolean, required
        - `type` 'automations', required
  - `updated_at` string, date-time, required
  - `version` integer, required

## Other responses

- `400`: Invalid JSON or request fields.
- `401`: Missing or invalid API key.
- `402`: The account has insufficient credits.
- `403`: The account cannot perform this operation.
- `404`: The requested resource was not found.
- `409`: The request conflicts with existing resource state.
- `429`: The account exceeded this operation's request rate.
- `500`: Unexpected Dexto failure.
- `502`: The upstream model provider failed.
- `503`: A required Dexto service is temporarily unavailable.

---

[API](https://skmtc.dev/dexto/apis/dexto-api.md) - [All operations](https://skmtc.dev/dexto/apis/dexto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dexto/apis/dexto-api/revisions/47eb880cffa5?raw)