StartAgentRunRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm/main/json-schema/gtm-start-agent-run-request-body-schema.json",
  "title": "StartAgentRunRequestBody",
  "description": "Request body for starting an agent run: a JSON:API document,\n`{ \"data\": { \"type\": \"StartAgentRunRequest\", \"attributes\": { ... } } }`,\nper the ZI public-API standard for request bodies. The run input lives in\n`data.attributes`; the same body is used by Start Agent Run and Start Agent\nRun (Stream).",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gtm-agent-api-v1-api-openapi.yml#/components/schemas/StartAgentRunRequestBody",
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "allOf": [
        {
          "$ref": "#/$defs/StartAgentRunRequest"
        }
      ],
      "description": "The primary data of the document"
    }
  },
  "$defs": {
    "AgentArtifactPart": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "Inline text content (text part)."
        },
        "file": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentFileContent"
            }
          ],
          "description": "File content by link or bytes (file part)."
        },
        "data": {
          "description": "Structured content with no downloadable form, e.g. a created CRM record or a data agent's structured result (data part)."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata for this part."
        }
      },
      "description": "One part of an artifact. Exactly one of `text`, `file`, or `data` is set,\nwhich determines the part's kind; `metadata` may accompany any. The\nmultipart protocol (chunk concatenation, rendering) keys off which one is\nset."
    },
    "AgentFileContent": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "format": "uri",
          "description": "Link to downloadable content (e.g. a generated document)."
        },
        "bytes": {
          "type": "string",
          "description": "Base64-encoded binary content."
        },
        "name": {
          "type": "string",
          "description": "Display filename."
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type of the file content."
        }
      },
      "description": "File content: exactly one of `uri` (a link, e.g. the platform's\ntoken-gated document route) or `bytes` (base64). `name` is always present\non emitted files (the server falls back to the object type rather than\nemit a nameless file)."
    },
    "AgentRunMessage": {
      "type": "object",
      "required": [
        "parts"
      ],
      "properties": {
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The message's content parts. Each is exactly one of `text`, `file`, or `data`; at most one `data` part is allowed."
        }
      },
      "description": "The caller's message to the agent -- the run's entire input, as an ordered\nlist of content parts (the same part shape artifacts use). There is no\n`role` (the sender is always the caller) and no message id (the run itself\nis the identity), so `parts` is the whole of it.\n\nParts by kind: `text` parts carry prose and are joined into the agent's\nprompt; a `data` part carries the structured argument object the agent's\n`inputSchema` data entry types; `file` parts are declared in the shape but not yet\naccepted. AT MOST ONE `data` part may be present -- parts have no names and\ntheir order carries no meaning, so a second anonymous payload would be\nstructure no schema can address; nest multiple structured payloads inside\nthe one data object instead."
    },
    "StartAgentRunAttributes": {
      "type": "object",
      "required": [
        "message"
      ],
      "properties": {
        "message": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunMessage"
            }
          ],
          "description": "The run's input, as one message of content parts: `{ \"parts\": [ { \"text\": \"...\" }, { \"data\": { ... } } ] }`. Prose goes in `text` parts; the structured argument object (typed by the agent's `inputSchema` data entry) goes in a single `data` part. See AgentRunMessage for the rules."
        },
        "contextId": {
          "type": "string",
          "description": "Conversation to continue this run within, as a UUID; omit to start fresh. Platform agents resume that conversation thread. Teams agents are single-shot: a supplied contextId is accepted and ignored (each Teams run gets a fresh server-minted context regardless). A malformed value returns `400` with a pointer to `/data/attributes/contextId`."
        },
        "returnImmediately": {
          "type": "boolean",
          "description": "Whether the request returns immediately. Default `true` starts the run asynchronously and returns the in-progress run while execution continues in the background. Set `false` to keep the connection open while the agent executes, up to 300 seconds. If the run does not complete within that window, the response returns the in-progress run and execution continues in the background. Ignored by Start Agent Run (Stream), which always streams.",
          "default": true
        },
        "taskId": {
          "type": "string",
          "description": "OPTIONAL, and omitted for almost every call. Omit it to START a new run\n(the default, and the only mode implemented today). Set it to an existing\nrun's id ONLY to CONTINUE that run when it is paused awaiting input\n(`TASK_STATE_INPUT_REQUIRED` / `TASK_STATE_AUTH_REQUIRED`): the message is\ndelivered as the answer and the run resumes. This is A2A's `Message.taskId`\n(the run id is the taskId).\n\nOnly agents whose `capabilities.interactive` is `true` accept a taskId;\nothers return `400`. An unknown run returns `404`; a terminal or\nnot-awaiting-input run returns `409`. No agent declares `interactive` yet,\nso continuation is not available in practice -- the field is specified for\nforward compatibility, not for use today."
        }
      },
      "description": "Attributes for starting an agent run."
    },
    "StartAgentRunRequest": {
      "type": "object",
      "required": [
        "type",
        "attributes"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "StartAgentRunRequest",
          "pattern": "StartAgentRunRequest"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/StartAgentRunAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        }
      },
      "description": "The run input as a JSON:API resource: `data.attributes` carries the message and optional contextId."
    }
  }
}