---
title: "Run an agent task"
method: POST
path: "/agent/run"
tags: ["agent"]
deprecated: true
---

# Run an agent task

`POST /agent/run`

> **Deprecated.**

Spawn a cloud agent with a prompt and optional configuration.
The agent will be queued for execution and assigned a unique run ID.

## Request body

- RunAgentRequest — Request body for creating a new agent run. Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required, except for handoff requests that set conversation_id.
  - `prompt` string — The prompt/instruction for the agent to execute. Required unless a skill is specified via the skill field, config.skill_spec, or config.skills. Handoff requests may omit prompt when conversation_id is set.
  - `mode` 'normal' | 'plan' | 'orchestrate' — Query mode for an agent run. - normal: Standard user query (default). - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution. - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
  - `skill` string — Skill specification to use as the base prompt for the agent. Supported formats: - "repo:skill_name" - Simple name in specific repo - "repo:skill_path" - Full path in specific repo - "org/repo:skill_name" - Simple name with org and repo - "org/repo:skill_path" - Full path with org and repo When provided, this takes precedence over config.skill_spec.
  - `config` AmbientAgentConfig — Configuration for a cloud agent run
    - `name` string — Human-readable label for grouping, filtering, and traceability. Automatically set to the skill name when running a skill-based agent. Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check") so you can filter and track them via the name query parameter on GET /agent/runs.
    - `model_id` string — LLM model to use (uses team default if not specified)
    - `base_prompt` string — Custom base prompt for the agent
    - `environment_id` string — UID of the environment to run the agent in
    - `runner_id` string — UID of the runner providing the run's compute (platform, instance shape, and setup commands). When omitted on a request, the runner is resolved at run creation from the agent's default runner, then the environment's default runner, and the resolved UID is recorded on the run.
    - `skill_spec` string — Skill specification identifying the primary agent skill to use. Format: "{owner}/{repo}:{skill_path}" Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" Mutually exclusive with skills in create/update requests. Responses include the first skills entry here for backward compatibility. Use the list agents endpoint to discover available skills.
    - `skills` string[] — Ordered skill specifications to attach to the run. Format: "{owner}/{repo}:{skill_path}" Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" Mutually exclusive with skill_spec in create/update requests.
    - `mcp_servers` object — Map of MCP server configurations by name
    - `computer_use_enabled` boolean — Controls whether computer use is enabled for this agent. If not set, defaults to true.
    - `idle_timeout_minutes` integer — Number of minutes to keep the agent environment alive after task completion. If not set, defaults to 10 minutes. Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).
    - `worker_host` string — Self-hosted worker ID that should execute this task. If not specified or set to "warp", the task runs on Warp-hosted workers.
    - `harness` Harness — Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. When stored as a named agent's default (create/update agent identity), this field replaces the deprecated base_harness/base_model pair: a non-oz type here requires the agent's base_model to be empty, since the two describe mutually exclusive default models.
      - `type` 'oz' | 'claude' | 'gemini' | 'codex' — The harness type identifier. - oz: Warp's built-in harness (default) - claude: Claude Code harness - gemini: Gemini CLI harness - codex: Codex CLI harness
      - `model_id` string — Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a non-oz harness; the top-level config model_id targets the built-in Oz harness instead. When omitted or empty, the harness uses its own default model.
      - `reasoning_level` string — Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a non-oz harness. Ignored by harnesses that do not support reasoning levels.
    - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
      - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
      - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".
    - `session_sharing` SessionSharingConfig — Configures sharing behavior for the run's shared session. When set, the worker emits `--share public:<level>` and the bundled Warp client applies an anyone-with-link ACL to the shared session once it has bootstrapped. The same ACL is mirrored onto the backing conversation so link viewers can read the conversation without being on the run's team. Subject to the workspace-level anyone-with-link sharing setting.
      - `public_access` 'VIEWER' | 'EDITOR' — Grants anyone-with-link access at the specified level to the run's shared session and backing conversation. - VIEWER: link viewers can read the session and conversation. - EDITOR: link viewers can also interact with the session. Anonymous (unauthenticated) reads are not supported in this release; link viewers must still be authenticated Warp users.
    - `memory_stores` MemoryStoreRef[] — Memory stores to attach to this run.
      - `uid` string, required — UID of the memory store.
      - `access` 'read_write' | 'read_only', required — Access level for the store.
      - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
    - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
      - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
        - `disabled` boolean — If true, opt out of Bedrock at this layer.
        - `role_arn` string — IAM role ARN to assume when calling Bedrock.
        - `region` string — AWS region used for STS when assuming the Bedrock inference role.
    - `credential_strategy` 'CREATOR' | 'EXECUTOR', nullable — Controls which principal's credentials are used when the platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on behalf of this run. - EXECUTOR (default when unset): credentials are sourced from the run's execution principal. For agent principals this produces a GitHub App installation token; for user principals this produces their personal OAuth token. - CREATOR: credentials are always sourced from the run creator, regardless of the execution principal. Useful when a service account executes the run but Git operations should authenticate as the human who triggered it. When unset, behavior is identical to EXECUTOR and no additional pre-flight validation is performed.
  - `title` string — Custom title for the run (auto-generated if not provided)
  - `team` boolean — Whether to create a team-owned run. Defaults to true for users on a single team.
  - `agent_identity_uid` string — Optional agent identity UID to use as the execution principal for the run. This is only valid for runs that are team owned.
  - `on_behalf_of` string — Optional email address or user ID of a Warp user to attribute the run to. When set, the resolved user becomes the run's creator instead of the caller. Only agent API keys may use this field, and the calling agent must have on_behalf_of enabled in its configuration (`on_behalf_of_enabled`), which a team admin must intentionally turn on per agent. The target user must be an active member of the run's owner team. Only valid for team-owned runs.
  - `conversation_id` string — Optional conversation ID to continue an existing conversation. If provided, the agent will continue from where the previous run left off.
  - `attachments` AttachmentInput[] — Optional file attachments to include with the prompt (max 5). Attachments are uploaded to cloud storage and made available to the agent.
    - `file_name` string, required — Name of the attached file
    - `mime_type` string, required — MIME type of the attachment. Supported image types: image/jpeg, image/png, image/gif, image/webp
    - `data` string, byte, required — Base64-encoded attachment data
  - `parent_run_id` string — Optional run ID of the parent that spawned this run. Used for orchestration hierarchies. The parent run must exist and be visible to the caller; otherwise the request is rejected with a 400. Child runs are also subject to the server's maximum orchestration depth, and requests that would exceed it are rejected with a 400.
  - `interactive` boolean — Whether the run should be interactive. If not set, defaults to false.
  - `metadata` RunMetadata — Custom key/value metadata attached to a run at creation time and immutable afterward. At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).

## Response `200`

Run created successfully

- RunAgentResponse
  - `run_id` string, required — Unique identifier for the created run
  - `task_id` string, required — Unique identifier for the task (same as run_id). Deprecated - use run_id instead.
  - `state` 'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED', required — Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: Run is actively being executed - SUCCEEDED: Run completed successfully - FAILED: Run failed - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - ERROR: Run encountered an error - CANCELLED: Run was cancelled by user
  - `at_capacity` boolean — Whether the system is at capacity when the run was created

## Other responses

- `400` — Invalid request (missing prompt, invalid config)
- `401` — Authentication required
- `403` — No permission to access referenced resources (environment, MCP servers)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)