---
title: "Run a cloud agent"
method: POST
path: "/agent/runs"
tags: ["agent"]
---

# Run a cloud agent

`POST /agent/runs`

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
    - `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 false.
    - `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.
      - `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
    - `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.
  - `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.
  - `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.
  - `interactive` boolean — Whether the run should be interactive. If not set, defaults to false.

## 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.net/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.net/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/warp/oz-agent-api/versions/97be876c33e3/schema)