AgentStreamEvent

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm/main/json-schema/gtm-agent-stream-event-schema.json",
  "title": "AgentStreamEvent",
  "description": "One server-sent event of a streaming run.\nEXACTLY ONE member is present per event, discriminating the frame kind:\n`task`, `statusUpdate`, `artifactUpdate`, or `message`.\n\nThe FIRST frame of every stream is ALWAYS a `task` frame (the task snapshot). On POST /runs/stream its `task.status.state` is\nTASK_STATE_SUBMITTED, emitted before execution begins. A streaming-only\nclient MUST read the run id from this first frame -- `task.id` -- because it\nis the only place a caller who did not start the run over a non-streaming\nendpoint receives it, and it is what Get Agent Run and Resume Agent Run\nStream need to poll the run or reconnect to its stream after a drop.\n\nThe typical sequence is:\n`task(SUBMITTED)` -> `statusUpdate(WORKING)` -> `artifactUpdate`* ->\n`statusUpdate(terminal)`. A `statusUpdate` frame whose `status.state` is\nterminal is always the LAST frame.",
  "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/AgentStreamEvent",
  "type": "object",
  "properties": {
    "task": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentTask"
        }
      ],
      "description": "A full task snapshot. The FIRST frame of every stream is a `task` frame: on POST /runs/stream it carries state TASK_STATE_SUBMITTED and the runId as `task.id`; on reconnect it carries the run's current state (and finalized `artifacts` if terminal)."
    },
    "statusUpdate": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentTaskStatusUpdateEvent"
        }
      ],
      "description": "The run entered a new state. Emitted for WORKING and for the terminal state; the terminal one is always the last frame."
    },
    "artifactUpdate": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentTaskArtifactUpdateEvent"
        }
      ],
      "description": "Artifact content produced by the run."
    },
    "message": {
      "allOf": [
        {
          "$ref": "#/$defs/AgentMessage"
        }
      ],
      "description": "A message. Reserved for future use; not currently emitted."
    }
  },
  "$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)."
    },
    "AgentMessage": {
      "type": "object",
      "required": [
        "messageId",
        "role",
        "parts"
      ],
      "properties": {
        "messageId": {
          "type": "string",
          "description": "Unique message identifier."
        },
        "contextId": {
          "type": "string",
          "description": "Conversation this message belongs to."
        },
        "taskId": {
          "type": "string",
          "description": "Run this message belongs to (the runId)."
        },
        "role": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentMessageRole"
            }
          ],
          "description": "Who the message is from."
        },
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The message's content parts."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata."
        }
      },
      "description": "A message: the shape carried by `status.message`, `history`, and the stream `message` frame (that frame is reserved for future use and not currently emitted)."
    },
    "AgentMessageRole": {
      "type": "string",
      "enum": [
        "ROLE_UNSPECIFIED",
        "ROLE_USER",
        "ROLE_AGENT"
      ],
      "description": "Who a message is from.",
      "x-enumDescriptions": {
        "ROLE_UNSPECIFIED": "Unspecified.",
        "ROLE_USER": "From the client to the agent.",
        "ROLE_AGENT": "From the agent to the client."
      }
    },
    "AgentRunArtifact": {
      "type": "object",
      "required": [
        "artifactId",
        "parts"
      ],
      "properties": {
        "artifactId": {
          "type": "string",
          "description": "Unique identifier of the artifact within the run."
        },
        "name": {
          "type": "string",
          "description": "Display name of the artifact."
        },
        "description": {
          "type": "string",
          "description": "What the artifact contains."
        },
        "parts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentArtifactPart"
          },
          "description": "The artifact's content parts. May carry more than one part, e.g. a text rendition and a structured `data` part."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata, e.g. the tool that created the artifact."
        }
      },
      "description": "An output artifact of a run. Available when the terminal\nstate is COMPLETED; a completed run carries at least one, and the response\nartifact is the complete record of the result. A chat agent returns a\nsingle text part; a data agent returns a multi-part artifact carrying both\nrenditions, e.g. `parts: [ { text }, { data } ]`, where the `data` part\nholds the structured payload. Over the stream the parts arrive across\nappend-only chunks (the final `lastChunk` event delivers the data part\nbeside the text tail), so a streaming client assembles the same artifact a\nGet Agent Run returns. The first artifact of a run is its response; see\nAgentRunAttributes.artifacts."
    },
    "AgentRunStatus": {
      "type": "object",
      "required": [
        "state"
      ],
      "properties": {
        "state": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentTaskState"
            }
          ],
          "description": "The task state."
        },
        "message": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentMessage"
            }
          ],
          "description": "A message elaborating this status, e.g. an agent's explanation of a failure or a prompt for further input."
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "When this state was entered."
        }
      },
      "description": "Current status of a run."
    },
    "AgentTask": {
      "type": "object",
      "required": [
        "id",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The run id. This is the first place a streaming-only client receives it: capture it here to poll Get Agent Run or reconnect via Resume Agent Run Stream after a drop."
        },
        "contextId": {
          "type": "string",
          "description": "The conversation this task belongs to. Always populated: the server mints the conversation before the opening frame when the caller did not supply one, so a streaming-only caller holds the conversation handle from frame one."
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunStatus"
            }
          ],
          "description": "Current task status."
        },
        "artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentRunArtifact"
          },
          "description": "Output artifacts."
        },
        "history": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AgentMessage"
          },
          "description": "Prior messages exchanged within the task's context."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Producer-defined metadata."
        }
      },
      "description": "A full task snapshot carried in a stream frame. Emitted as the FIRST frame of every stream."
    },
    "AgentTaskArtifactUpdateEvent": {
      "type": "object",
      "required": [
        "taskId",
        "artifact"
      ],
      "properties": {
        "taskId": {
          "type": "string",
          "description": "The run this event belongs to (the runId)."
        },
        "contextId": {
          "type": "string",
          "description": "The conversation the run belongs to (the platform thread, or the server-minted per-run context for Teams). Populated on every artifact event."
        },
        "artifact": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunArtifact"
            }
          ],
          "description": "The artifact chunk."
        },
        "append": {
          "type": "boolean",
          "description": "Omitted or false on the first chunk of an artifact; true when this chunk's parts append to previously streamed content. An explicit false mid-stream means the artifact restarted and the accumulated content should be discarded."
        },
        "lastChunk": {
          "type": "boolean",
          "description": "True on the artifact's final chunk."
        }
      },
      "description": "Artifact content produced mid-run. Chunks\nsharing an `artifactId` are concatenated by the client in arrival order."
    },
    "AgentTaskState": {
      "type": "string",
      "enum": [
        "TASK_STATE_UNSPECIFIED",
        "TASK_STATE_SUBMITTED",
        "TASK_STATE_WORKING",
        "TASK_STATE_INPUT_REQUIRED",
        "TASK_STATE_AUTH_REQUIRED",
        "TASK_STATE_COMPLETED",
        "TASK_STATE_FAILED",
        "TASK_STATE_CANCELED",
        "TASK_STATE_REJECTED"
      ],
      "description": "Task lifecycle states for a run.\nTerminal: COMPLETED, FAILED, CANCELED, REJECTED. Interrupted:\nINPUT_REQUIRED, AUTH_REQUIRED. Everything else is non-terminal.\nConsumers must tolerate unknown values, treating UNSPECIFIED as the\nfallback for states this version does not define.\n\nThe service currently emits SUBMITTED, WORKING, COMPLETED, and FAILED\n(plus the UNSPECIFIED fallback). CANCELED and REJECTED are reserved for\ncancellation support; INPUT_REQUIRED and AUTH_REQUIRED are reserved for\ninteractive runs. Consumers should handle all nine states.",
      "x-enumDescriptions": {
        "TASK_STATE_UNSPECIFIED": "The task state is unknown or has not been set. Non-terminal.",
        "TASK_STATE_SUBMITTED": "The task was accepted and is waiting to begin. Non-terminal.",
        "TASK_STATE_WORKING": "The agent is actively processing the task. Non-terminal.",
        "TASK_STATE_INPUT_REQUIRED": "The agent needs additional user or client input. Interrupted.",
        "TASK_STATE_AUTH_REQUIRED": "Additional authentication is required. Interrupted.",
        "TASK_STATE_COMPLETED": "The task completed successfully. Terminal.",
        "TASK_STATE_FAILED": "The task ended because of an execution error. Terminal.",
        "TASK_STATE_CANCELED": "The task was canceled before completion. Terminal.",
        "TASK_STATE_REJECTED": "The agent declined or could not accept the task. Terminal."
      }
    },
    "AgentTaskStatusUpdateEvent": {
      "type": "object",
      "required": [
        "taskId",
        "status"
      ],
      "properties": {
        "taskId": {
          "type": "string",
          "description": "The run this event belongs to: the runId."
        },
        "contextId": {
          "type": "string",
          "description": "The conversation the run belongs to. Populated on every event from the WORKING frame onward: the platform thread for platform agents, or the server-minted per-run context for Teams agents."
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/$defs/AgentRunStatus"
            }
          ],
          "description": "The status entered."
        }
      },
      "description": "The run entered a new state. Emitted for\nTASK_STATE_WORKING once execution begins and again for the terminal state;\nthe terminal one is always the LAST frame of the stream. The opening\nSUBMITTED state is carried by the `task` frame, not by one of these (see\nAgentStreamEvent)."
    }
  }
}