Warp · Schema

RunAgentRequest

Request body for creating a new Warp Oz cloud agent run.

Developer ToolsTerminalAI AgentsCloud AgentsAgentic Development

Properties

Name	Type	Description
prompt	string	The prompt/instruction for the agent to execute. Required unless a skill is specified.
mode	string	Optional query mode for the run.
skill	string	Skill specification to use as the base prompt. Formats: 'repo:skill_name', 'repo:skill_path', 'org/repo:skill_name', 'org/repo:skill_path'.
config	object	Ambient agent configuration for the run
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. Only valid for team-owned runs.
conversation_id	string	Optional conversation ID to continue an existing conversation.
attachments	array	Optional file attachments to include with the prompt (max 5).
parent_run_id	string	Optional run ID of the parent that spawned this run (for orchestration hierarchies).
interactive	boolean	Whether the run should be interactive. Defaults to false.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api-evangelist.github.io/warp/json-schema/warp-run-agent-request-schema.json",
  "title": "RunAgentRequest",
  "description": "Request body for creating a new Warp Oz cloud agent run.",
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The prompt/instruction for the agent to execute. Required unless a skill is specified."
    },
    "mode": {
      "type": "string",
      "description": "Optional query mode for the run.",
      "enum": ["normal", "plan", "auto"],
      "default": "normal"
    },
    "skill": {
      "type": "string",
      "description": "Skill specification to use as the base prompt. Formats: 'repo:skill_name', 'repo:skill_path', 'org/repo:skill_name', 'org/repo:skill_path'."
    },
    "config": {
      "type": "object",
      "description": "Ambient agent configuration for the run",
      "properties": {
        "skill_spec": { "type": "string" },
        "skills": {
          "type": "array",
          "items": { "type": "string" }
        },
        "environment_uid": { "type": "string" },
        "model": { "type": "string" },
        "harness": {
          "type": "object",
          "properties": {
            "repo": { "type": "string" },
            "branch": { "type": "string" },
            "auth_secrets": {
              "type": "object",
              "properties": {
                "github_token": { "type": "string" }
              }
            }
          }
        },
        "mcp_servers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "command": { "type": "string" },
              "args": { "type": "array", "items": { "type": "string" } },
              "env": { "type": "object" }
            }
          }
        }
      }
    },
    "title": {
      "type": "string",
      "description": "Custom title for the run (auto-generated if not provided)"
    },
    "team": {
      "type": "boolean",
      "description": "Whether to create a team-owned run. Defaults to true for users on a single team."
    },
    "agent_identity_uid": {
      "type": "string",
      "description": "Optional agent identity UID to use as the execution principal. Only valid for team-owned runs."
    },
    "conversation_id": {
      "type": "string",
      "description": "Optional conversation ID to continue an existing conversation."
    },
    "attachments": {
      "type": "array",
      "maxItems": 5,
      "description": "Optional file attachments to include with the prompt (max 5).",
      "items": {
        "type": "object",
        "properties": {
          "content": { "type": "string", "description": "Base64-encoded file content" },
          "filename": { "type": "string" },
          "content_type": { "type": "string" }
        }
      }
    },
    "parent_run_id": {
      "type": "string",
      "description": "Optional run ID of the parent that spawned this run (for orchestration hierarchies)."
    },
    "interactive": {
      "type": "boolean",
      "description": "Whether the run should be interactive. Defaults to false.",
      "default": false
    }
  }
}