WAwarp
Agents

Create an agent

Changed on

Create a new agent in the caller's active team. Agents act autonomously with their own permissions, configuration, and identity.

post/agent/identities

Request

  • Base URL
    https://app.warp.dev/api/v1
  • Auth
    HTTP bearer

Headers

X-Warp-Team-Uidstring

UID of the team to use as the request's active team. Ignored for service-account callers, which always act as their bound team.

Request body

namestring required

A name for the agent

descriptionstring nullable

Optional description of the agent

promptstring nullable

Optional base prompt for this agent

environment_idstring nullable

Optional default cloud environment ID for runs executed by this agent. The environment must be owned by the same team as the agent.

default_runner_uidstring nullable

Optional default runner UID for runs executed by this agent. When set, it overrides the selected environment's default runner for runs that do not specify their own runner_id. The editor must have View permission on the referenced runner.

skillsstring[]

Optional list of skill specs to associate with the agent. Format: "{owner}/{repo}:{skill_path}" (e.g., "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"). Each spec is validated and normalized at attach time using the team's GitHub credentials; inaccessible or malformed specs are rejected.

base_modelstring nullable

Optional base model for runs executed by this agent.

mcp_serversobject

Optional map of MCP server configurations by name to attach to runs executed by this agent. Run-level MCP config takes precedence over this agent-level default.

base_harnessstring nullable

Optional default harness for runs executed by this agent. Deprecated - use harness instead. Kept for backward compatibility; when both are sent, harness is authoritative and a conflicting type is rejected with invalid_request.

credential_strategy'CREATOR' | 'EXECUTOR'

Default credential strategy for runs executed by a named agent; an agent may leave this unset (see AgentResponse.credential_strategy for the full resolution order).

  • EXECUTOR: runs authenticate with the named agent's own credentials (e.g. a GitHub App installation token for the agent's team).
  • CREATOR: runs authenticate with the credentials of the principal that created the run.
on_behalf_of_enabledboolean

Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member. Defaults to false. Only team admins may set this field.

worker_hoststring nullable

Optional default worker host for runs executed by this agent; omission, null, or an empty value stores no Agent default, in which case the workspace default applies. A non-empty value is trimmed and stored (use "warp" to force Warp-hosted execution over a self-hosted workspace default), and is resolved in this order:

  1. The host specified on the run itself
  2. The agent's default host
  3. The workspace default host

Response

Agent created successfully

uidstring required

Unique identifier for the agent

namestring required

Name of the agent

descriptionstring nullable

Optional description of the agent

promptstring nullable

Optional base prompt for this agent

environment_idstring

Default cloud environment ID for runs executed by this agent; the precedence order for environment resolution is:

  1. The environment specified on the run itself
  2. The agent's default environment
  3. An empty environment
default_runner_uidstring required

Default runner UID for runs executed by this agent; when set, it overrides the selected environment's default runner for runs that do not specify their own runner_id. The precedence order for runner resolution is:

  1. The runner specified on the run itself
  2. The agent's default runner
  3. The selected environment's default runner
  4. The environment's legacy inline compute fields
  5. System defaults
availableboolean required

Whether the agent is currently enabled. Defaults to true.

created_atstring date-time required

When the agent was created (RFC3339)

updated_atstring date-time required

When the agent was last updated (RFC3339)

skillsstring[] required

Ordered list of normalized skill specs associated with this agent. Always present; empty when no skills are attached.

base_modelstring

Base model for runs executed by this agent; the precedence order for model resolution is:

  1. The model specified on the run itself
  2. The agent's base model
  3. The team's default model
mcp_serversobject

MCP server configurations attached to this agent by default. Run-level MCP config takes precedence over this agent-level default.

base_harnessstring

Default harness for runs executed by this agent; the precedence order for harness resolution is:

  1. The harness specified on the run itself
  2. The agent's base harness
  3. Warp Deprecated: use harness instead, which carries the full {type, model_id, reasoning_level} default.
credential_strategy'CREATOR' | 'EXECUTOR'

Default credential strategy for runs executed by a named agent; an agent may leave this unset (see AgentResponse.credential_strategy for the full resolution order).

  • EXECUTOR: runs authenticate with the named agent's own credentials (e.g. a GitHub App installation token for the agent's team).
  • CREATOR: runs authenticate with the credentials of the principal that created the run.
on_behalf_of_enabledboolean

Whether runs created with this agent's API key may use the on_behalf_of field to attribute runs to another team member.

worker_hoststring

Default worker host for runs executed by this agent, or empty when unset; the precedence order for worker host resolution is:

  1. The host specified on the run itself
  2. The agent's default host
  3. The workspace default host

Changes

  • 2c45dcc0a13eRevision changes
    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • breaking

      removed the enum value claude of the request property /////

    • breaking

      removed the enum value codex of the request property /////

    • breaking

      removed the enum value gemini of the request property /////

    • breaking

      removed the enum value oz of the request property /////

    • breaking

      the ///// request property type changed from string to no type

    • breaking

      added subschema #1 to the ///// response property oneOf list for the response status

    • breaking

      the ///// response's property type changed from string to no type for status

    • warning

      removed from the request property allOf list

    • info

      added the new optional request property /////

    • info

      added subschema #2 to the request property oneOf list

    • info

      added subschema #1 to the ///// request property oneOf list

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      removed the claude enum value from the ///// response property for the response status

    • info

      removed the codex enum value from the ///// response property for the response status

    • info

      removed the gemini enum value from the ///// response property for the response status

    • info

      removed the oz enum value from the ///// response property for the response status

  • 4a13a21e49d9Revision changes
    • info

      added the new optional header request parameter X-Warp-Team-Uid