@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.1

package/python-runtime/python/lib/python3.12/site-packages/ag_ui/_generated/models.py

@@ -0,0 +1,2825 @@
+# @generated by spec/generator — DO NOT EDIT.
+# Source: https://ag-ui.com/spec/1.0/schema.json
+# Regenerate: pnpm --filter @ag-ui/spec generate
+
+
+
+from enum import Enum
+from typing import Annotated, Any, Dict, FrozenSet, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, model_serializer
+from pydantic.alias_generators import to_camel
+from pydantic.functional_serializers import SerializerFunctionWrapHandler
+
+
+_OMITTABLE_KEYS_CACHE_ATTR = "_agui_omittable_keys"
+
+
+class GeneratedBaseModel(BaseModel):
+    """
+    The generated base model — the public SDK's ergonomics, not a wire
+    artifact. Wire names are camelCase behind snake_case attributes, and both
+    spellings populate a model, because Python callers construct with the
+    attribute names. Unknown fields are kept, not dropped, so a boundary that
+    wants to warn about them can still see them and a re-serialising
+    intermediary does not lose them. Coercion is pydantic's default: the
+    strict contract is the specification's validation corpus, not this class.
+
+    Serialization omits every optional field that has no value instead of
+    writing it out as JSON ``null``. Pydantic's default is to include it, which
+    made this SDK the only AG-UI producer that put ``null`` on the wire where
+    TypeScript simply left the key out. Omission is applied here, in the base
+    model, so it holds on every serialization path (``model_dump``,
+    ``model_dump_json``, nesting inside another model, and any
+    ``TypeAdapter``) rather than depending on each call site remembering
+    ``exclude_none=True``.
+
+    "Has no value" means a field that is declared optional *and* defaults to
+    ``None`` — exactly the set the contract lets a producer leave out. Nulls
+    that carry meaning are untouched: a required field (CUSTOM.value, say), a
+    ``None`` inside a ``dict``/``list`` value, and any extra field all
+    serialize as ``null``.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        alias_generator=to_camel,
+        populate_by_name=True,
+    )
+
+    @classmethod
+    def _omittable_keys(cls) -> FrozenSet[str]:
+        """
+        The serialized keys that may be dropped when their value is ``None``.
+
+        Both the field name and its alias are included, because the caller
+        chooses between them with ``by_alias``. Cached per class in the class's
+        own ``__dict__`` so a subclass never inherits its parent's answer.
+        """
+        cached = cls.__dict__.get(_OMITTABLE_KEYS_CACHE_ATTR)
+        if cached is None:
+            keys = set()
+            for name, field in cls.model_fields.items():
+                if not field.is_required() and field.default is None:
+                    keys.add(name)
+                    if field.alias is not None:
+                        keys.add(field.alias)
+                    if field.serialization_alias is not None:
+                        keys.add(field.serialization_alias)
+            cached = frozenset(keys)
+            setattr(cls, _OMITTABLE_KEYS_CACHE_ATTR, cached)
+        return cached
+
+    @model_serializer(mode="wrap")
+    def _omit_fields_without_value(self, handler: SerializerFunctionWrapHandler):
+        # Deliberately unannotated return: annotating it (``Dict[str, Any]``, say)
+        # makes Pydantic replace the model's serialization JSON schema with a bare
+        # ``{"type": "object"}``. Left off, the handler's own schema is kept.
+        serialized = handler(self)
+        omittable = type(self)._omittable_keys()
+        return {
+            key: value
+            for key, value in serialized.items()
+            if value is not None or key not in omittable
+        }
+
+
+class EventType(str, Enum):
+    """The discriminator carried by every event."""
+
+    TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
+    TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
+    TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
+    TEXT_MESSAGE_CHUNK = "TEXT_MESSAGE_CHUNK"
+    TOOL_CALL_START = "TOOL_CALL_START"
+    TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
+    TOOL_CALL_END = "TOOL_CALL_END"
+    TOOL_CALL_CHUNK = "TOOL_CALL_CHUNK"
+    TOOL_CALL_RESULT = "TOOL_CALL_RESULT"
+    STATE_SNAPSHOT = "STATE_SNAPSHOT"
+    STATE_DELTA = "STATE_DELTA"
+    MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT"
+    ACTIVITY_SNAPSHOT = "ACTIVITY_SNAPSHOT"
+    ACTIVITY_DELTA = "ACTIVITY_DELTA"
+    RAW = "RAW"
+    CUSTOM = "CUSTOM"
+    RUN_STARTED = "RUN_STARTED"
+    RUN_FINISHED = "RUN_FINISHED"
+    RUN_ERROR = "RUN_ERROR"
+    STEP_STARTED = "STEP_STARTED"
+    STEP_FINISHED = "STEP_FINISHED"
+    REASONING_START = "REASONING_START"
+    REASONING_MESSAGE_START = "REASONING_MESSAGE_START"
+    REASONING_MESSAGE_CONTENT = "REASONING_MESSAGE_CONTENT"
+    REASONING_MESSAGE_END = "REASONING_MESSAGE_END"
+    REASONING_MESSAGE_CHUNK = "REASONING_MESSAGE_CHUNK"
+    REASONING_END = "REASONING_END"
+    REASONING_ENCRYPTED_VALUE = "REASONING_ENCRYPTED_VALUE"
+    SUBAGENT_STARTED = "SUBAGENT_STARTED"
+    SUBAGENT_FINISHED = "SUBAGENT_FINISHED"
+    SUBAGENT_ERROR = "SUBAGENT_ERROR"
+
+
+Metadata = Dict[str, Any]
+"""
+Extra information attached to an event, a message, a tool call, a tool, an
+interrupt or a resume entry. Open by key: any JSON value is allowed under a
+key, including null, because a null there is meaningful data. The object
+itself may be absent but is never null when present. The key ag-ui is
+reserved for the protocol's own use; reservation is by convention, since
+validating the shape of a key's value would contradict being open by key.
+"""
+
+
+SubagentRunId = str
+"""
+An opaque handle for one subagent invocation, not a reusable name for a
+subagent definition: two invocations of the same subagent carry two
+different values. Named to mirror runId one level down, the way the
+subagent's name mirrors agentId.
+"""
+
+
+TextMessageRole = Literal["developer", "system", "assistant", "user"]
+"""
+The roles a streamed text message may take. Excludes tool, which is carried
+by TOOL_CALL_RESULT rather than streamed as text.
+"""
+
+
+class Attributable(GeneratedBaseModel):
+    """
+    Composed into everything that can belong to a subagent's work: the
+    events that describe content or progress, the message types, and each
+    interrupt. Run-scoped events omit it — RUN_STARTED, RUN_FINISHED and
+    RUN_ERROR describe the run itself and MESSAGES_SNAPSHOT is
+    conversation-wide, so none of them can belong to one subagent. A tool
+    call omits it too and inherits its containing message's attribution.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+
+
+class BaseEvent(GeneratedBaseModel):
+    """
+    The fields every event carries, whatever its type. Composed into each
+    event definition rather than repeated, so a change here reaches every
+    event at once.
+    """
+
+    type: EventType
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+
+
+class BaseMessage(GeneratedBaseModel):
+    """
+    The fields shared by the developer, system, assistant and user messages.
+    Deliberately excludes content, because a user message's content may be
+    an array while the others are strings, and composition here intersects
+    rather than overrides: a base that constrained content to a string would
+    make an array content invalid. The tool, activity and reasoning messages
+    do not compose this, because they carry no name.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message within the conversation."""
+    role: str
+    """
+    Who the message is from. Each message definition narrows this to a
+    single value.
+    """
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """
+    A provider's opaque artefact belonging to this message, stored by a
+    consumer and returned on a later turn.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+
+
+class TextMessageStartEvent(BaseEvent):
+    """
+    Opens a streamed text message. The content arrives as
+    TEXT_MESSAGE_CONTENT events and the message closes with
+    TEXT_MESSAGE_END.
+    """
+
+    type: Literal[EventType.TEXT_MESSAGE_START] = EventType.TEXT_MESSAGE_START
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """
+    Identifies the message this stream builds, and ties the later content
+    and end events to it.
+    """
+    role: Optional[TextMessageRole] = Field(default=None)
+    """
+    Who the message is from. An absent role means assistant; that meaning is
+    normative and stated in the prose, because a validator treats a default
+    as documentation rather than as behaviour.
+    """
+    name: Optional[str] = Field(default=None)
+    """
+    An optional display name for the author, for providers that distinguish
+    several participants in one role.
+    """
+
+
+class TextMessageContentEvent(BaseEvent):
+    """Appends a fragment to a streamed text message."""
+
+    type: Literal[EventType.TEXT_MESSAGE_CONTENT] = EventType.TEXT_MESSAGE_CONTENT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The message this fragment belongs to."""
+    delta: str
+    """
+    The fragment to append. May be the empty string: providers emit empty
+    deltas as keep-alives and while a tool call is being decided, and
+    rejecting them would kill runs that are working correctly.
+    """
+
+
+class TextMessageEndEvent(BaseEvent):
+    """Closes a streamed text message."""
+
+    type: Literal[EventType.TEXT_MESSAGE_END] = EventType.TEXT_MESSAGE_END
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The message being closed."""
+
+
+class TextMessageChunkEvent(BaseEvent):
+    """
+    A shorthand that stands in for a start, content and end sequence, for
+    producers that cannot know in advance where a message begins. Every
+    field is optional because a continuation chunk omits what has not
+    changed; which message a field-less chunk continues is a sequence
+    question the prose specification answers.
+    """
+
+    type: Literal[EventType.TEXT_MESSAGE_CHUNK] = EventType.TEXT_MESSAGE_CHUNK
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: Optional[str] = Field(default=None)
+    """
+    The message this chunk belongs to. Absent continues the message already
+    open.
+    """
+    role: Optional[TextMessageRole] = Field(default=None)
+    """Who the message is from, on the chunk that opens it."""
+    delta: Optional[str] = Field(default=None)
+    """The fragment to append. May be the empty string."""
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+
+
+class ToolCallStartEvent(BaseEvent):
+    """
+    Opens a tool call. The arguments arrive as TOOL_CALL_ARGS events and the
+    call closes with TOOL_CALL_END.
+    """
+
+    type: Literal[EventType.TOOL_CALL_START] = EventType.TOOL_CALL_START
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    tool_call_id: str
+    """
+    Identifies the call, and ties the later args, end and result events to
+    it.
+    """
+    tool_call_name: str
+    """Which tool is being called."""
+    parent_message_id: Optional[str] = Field(default=None)
+    """
+    The assistant message that holds this call. Absent means the producer
+    did not attribute it to one.
+    """
+
+
+class ToolCallArgsEvent(BaseEvent):
+    """Appends a fragment of a tool call's arguments."""
+
+    type: Literal[EventType.TOOL_CALL_ARGS] = EventType.TOOL_CALL_ARGS
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    tool_call_id: str
+    """The call these arguments belong to."""
+    delta: str
+    """
+    A fragment of the arguments, which concatenate into the call's argument
+    text — conventionally a JSON document, though the protocol does not
+    validate it (see FunctionCall.arguments). Deliberately a string rather
+    than parsed JSON: a fragment is not itself a document. May be the empty
+    string.
+    """
+
+
+class ToolCallEndEvent(BaseEvent):
+    """Closes a tool call, meaning its arguments are complete."""
+
+    type: Literal[EventType.TOOL_CALL_END] = EventType.TOOL_CALL_END
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    tool_call_id: str
+    """The call being closed."""
+
+
+class ToolCallChunkEvent(BaseEvent):
+    """
+    A shorthand that stands in for a tool call's start, args and end
+    sequence. Every field is optional for the same reason as
+    TEXT_MESSAGE_CHUNK.
+    """
+
+    type: Literal[EventType.TOOL_CALL_CHUNK] = EventType.TOOL_CALL_CHUNK
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    tool_call_id: Optional[str] = Field(default=None)
+    """The call this chunk belongs to. Absent continues the call already open."""
+    tool_call_name: Optional[str] = Field(default=None)
+    """Which tool is being called, on the chunk that opens it."""
+    parent_message_id: Optional[str] = Field(default=None)
+    """The assistant message that holds this call."""
+    delta: Optional[str] = Field(default=None)
+    """A fragment of the arguments. May be the empty string."""
+
+
+class TextPart(GeneratedBaseModel):
+    """A text part."""
+
+    type: Literal["text"] = "text"
+    """Discriminator."""
+    id: Optional[str] = Field(default=None)
+    """
+    Identifies this part within its message. Optional, and nothing reads it
+    yet: reserved so that a streamed part can be matched to its entry in
+    history once assistant messages carry parts too.
+    """
+    text: str
+    """The text."""
+    metadata: Optional[Any] = Field(default=None)
+    """
+    Extra information about this part. Unconstrained, as on the media parts.
+    This is where a text search hit carries its source and title, rather
+    than the protocol modelling a search-result part of its own.
+    """
+
+
+class DataSource(GeneratedBaseModel):
+    """Bytes carried inline."""
+
+    type: Literal["data"] = "data"
+    """Discriminator."""
+    value: str
+    """
+    The bytes, base64-encoded. contentEncoding is an annotation rather than
+    a constraint in 2020-12, so a malformed string still validates here;
+    rejecting one is the decoder's job.
+    """
+    mime_type: str
+    """
+    What the bytes are. Required here, unlike on a URL source, because
+    nothing else can tell a consumer how to read them.
+    """
+
+
+class UrlSource(GeneratedBaseModel):
+    """Bytes referenced by URL, fetched by whoever needs them."""
+
+    type: Literal["url"] = "url"
+    """Discriminator."""
+    value: str
+    """
+    The URL. Deliberately not constrained to a URI format, so a scheme a
+    producer already uses is not rejected here.
+    """
+    mime_type: Optional[str] = Field(default=None)
+    """
+    What the resource is, when the producer knows. Optional, because the
+    response can say.
+    """
+
+
+class FileSource(GeneratedBaseModel):
+    """
+    Bytes already at the provider, named by a handle the provider issued: an
+    OpenAI or Anthropic file id, a Gemini file URI, a storage URL only that
+    provider can read. No bytes travel and nothing is fetched. Only the
+    provider that minted the handle can resolve it; a peer that cannot drops
+    the part as it drops any part it cannot use.
+    """
+
+    type: Literal["file"] = "file"
+    """Discriminator."""
+    value: str
+    """
+    The handle, exactly as the provider issued it. Opaque: a consumer MUST
+    NOT fetch it, parse it or read a scheme out of it.
+    """
+    provider: Optional[str] = Field(default=None)
+    """
+    Who issued the handle, when the producer knows. Optional: an agent
+    already knows which provider it talks to. When present, SHOULD be the
+    lowercase vendor id (openai, anthropic, google) that TokenUsage.provider
+    uses, so a peer can tell before sending whether a handle is one it can
+    use.
+    """
+    mime_type: Optional[str] = Field(default=None)
+    """
+    What the file is, when the producer knows. Optional, because the
+    provider that holds the bytes knows.
+    """
+
+
+PartSource = Annotated[
+    Union[DataSource, UrlSource, FileSource],
+    Field(discriminator="type"),
+]
+"""
+Where a media part's bytes come from: carried inline, referenced by URL, or
+already at the provider under a handle it issued.
+"""
+
+
+class ImagePart(GeneratedBaseModel):
+    """An image part."""
+
+    type: Literal["image"] = "image"
+    """Discriminator."""
+    id: Optional[str] = Field(default=None)
+    """
+    Identifies this part within its message. Optional, and nothing reads it
+    yet: reserved as on the text part.
+    """
+    source: PartSource
+    """Where the image comes from."""
+    metadata: Optional[Any] = Field(default=None)
+    """
+    Extra information about this part. Unconstrained rather than an object:
+    inherited from the SDKs, which declare it unknown rather than a record;
+    listed under known divergences in the README rather than resolved here.
+    """
+
+
+class AudioPart(GeneratedBaseModel):
+    """An audio part."""
+
+    type: Literal["audio"] = "audio"
+    """Discriminator."""
+    id: Optional[str] = Field(default=None)
+    """
+    Identifies this part within its message. Optional, and nothing reads it
+    yet: reserved as on the text part.
+    """
+    source: PartSource
+    """Where the audio comes from."""
+    metadata: Optional[Any] = Field(default=None)
+    """
+    Extra information about this part. Unconstrained, as on the other media
+    parts.
+    """
+
+
+class VideoPart(GeneratedBaseModel):
+    """A video part."""
+
+    type: Literal["video"] = "video"
+    """Discriminator."""
+    id: Optional[str] = Field(default=None)
+    """
+    Identifies this part within its message. Optional, and nothing reads it
+    yet: reserved as on the text part.
+    """
+    source: PartSource
+    """Where the video comes from."""
+    metadata: Optional[Any] = Field(default=None)
+    """
+    Extra information about this part. Unconstrained, as on the other media
+    parts.
+    """
+
+
+class DocumentPart(GeneratedBaseModel):
+    """A document part."""
+
+    type: Literal["document"] = "document"
+    """Discriminator."""
+    id: Optional[str] = Field(default=None)
+    """
+    Identifies this part within its message. Optional, and nothing reads it
+    yet: reserved as on the text part.
+    """
+    source: PartSource
+    """Where the document comes from."""
+    metadata: Optional[Any] = Field(default=None)
+    """
+    Extra information about this part. Unconstrained, as on the other media
+    parts.
+    """
+
+
+ContentPart = Annotated[
+    Union[TextPart, ImagePart, AudioPart, VideoPart, DocumentPart],
+    Field(discriminator="type"),
+]
+"""
+One part of a message body: what a person sends in a user message, or what a
+tool returns in a tool message. Discriminated by type. Named by what the
+part is rather than by direction, because the same part travels into the
+model inside a user message and back out of the stream inside a tool result.
+"""
+
+
+class ToolCallResultEvent(BaseEvent):
+    """
+    Carries what a tool returned. Mints a tool message rather than appending
+    to an existing one, which is why it has its own messageId.
+    """
+
+    type: Literal[EventType.TOOL_CALL_RESULT] = EventType.TOOL_CALL_RESULT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The tool message this result becomes."""
+    tool_call_id: str
+    """The call being answered."""
+    content: Union[str, List[ContentPart]]
+    """
+    What the tool returned: either plain text, or an ordered list of parts,
+    exactly as on the tool message this event mints. A tool returning
+    structured data serialises it into text; media travel as parts of their
+    own.
+    """
+    role: Optional[Literal["tool"]] = Field(default=None)
+    """
+    Present only for symmetry with the message it mints; the value is fixed,
+    so a producer may leave it out.
+    """
+
+
+State = Any
+"""
+Agent state. Any JSON value: the protocol carries state without interpreting
+it, so an object, an array, a string and a number are all valid.
+"""
+
+
+class StateSnapshotEvent(BaseEvent):
+    """
+    Replaces the agent state wholesale. Sent when a delta cannot express the
+    change, or to resynchronise a consumer.
+    """
+
+    type: Literal[EventType.STATE_SNAPSHOT] = EventType.STATE_SNAPSHOT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    snapshot: State
+    """The complete new state."""
+
+
+JsonPointer = Annotated[str, Field(pattern=r"^(/([^/~]|~[01])*)*$")]
+"""
+A JSON Pointer as defined by RFC 6901. Either the empty string, meaning the
+whole document, or a sequence of slash-prefixed reference tokens in which a
+tilde is escaped as ~0 and a slash as ~1. A value with no leading slash, or
+a tilde followed by anything other than 0 or 1, is not a JSON Pointer.
+"""
+
+
+class AddOperation(GeneratedBaseModel):
+    """Inserts value at path. RFC 6902 section 4.1."""
+
+    op: Literal["add"] = "add"
+    """Discriminator for the add operation."""
+    path: JsonPointer
+    """Where to insert the value."""
+    value: Any
+    """
+    The value to insert. Any JSON value, including null, which is a
+    legitimate thing to add.
+    """
+
+
+class RemoveOperation(GeneratedBaseModel):
+    """Removes the value at path. RFC 6902 section 4.2."""
+
+    op: Literal["remove"] = "remove"
+    """Discriminator for the remove operation."""
+    path: JsonPointer
+    """What to remove."""
+
+
+class ReplaceOperation(GeneratedBaseModel):
+    """Replaces the value at path. RFC 6902 section 4.3."""
+
+    op: Literal["replace"] = "replace"
+    """Discriminator for the replace operation."""
+    path: JsonPointer
+    """What to replace."""
+    value: Any
+    """The replacement. Any JSON value, including null."""
+
+
+class MoveOperation(GeneratedBaseModel):
+    """Moves the value at from to path. RFC 6902 section 4.4."""
+
+    model_config = ConfigDict(serialize_by_alias=True)
+
+    op: Literal["move"] = "move"
+    """Discriminator for the move operation."""
+    from_: JsonPointer = Field(alias="from")
+    """Where the value is moved from."""
+    path: JsonPointer
+    """Where the value is moved to."""
+
+
+class CopyOperation(GeneratedBaseModel):
+    """Copies the value at from to path. RFC 6902 section 4.5."""
+
+    model_config = ConfigDict(serialize_by_alias=True)
+
+    op: Literal["copy"] = "copy"
+    """Discriminator for the copy operation."""
+    from_: JsonPointer = Field(alias="from")
+    """Where the value is copied from."""
+    path: JsonPointer
+    """Where the value is copied to."""
+
+
+class TestOperation(GeneratedBaseModel):
+    """Asserts that the value at path equals value. RFC 6902 section 4.6."""
+
+    op: Literal["test"] = "test"
+    """Discriminator for the test operation."""
+    path: JsonPointer
+    """What to compare."""
+    value: Any
+    """The value the target must equal. Any JSON value, including null."""
+
+
+JsonPatchOperation = Annotated[
+    Union[AddOperation, RemoveOperation, ReplaceOperation, MoveOperation, CopyOperation, TestOperation],
+    Field(discriminator="op"),
+]
+"""
+A single RFC 6902 operation. Exactly one of the operation shapes must match,
+discriminated by op. Unlike the protocol's own objects, the operations are
+open: RFC 6902 section 4 requires members an operation does not define to be
+ignored rather than rejected, so a remove carrying a leftover value is a
+valid patch. Two of the RFC's rules are relations between values rather than
+shapes, so no static schema can express them and neither is checked here: a
+move whose from is a proper prefix of its path (section 4.4), and any
+operation whose pointer does not resolve in the target document. Both are
+the applier's to reject.
+"""
+
+
+JsonPatch = List[JsonPatchOperation]
+"""
+A JSON Patch document as defined by RFC 6902, referenced by
+STATE_DELTA.delta and ACTIVITY_DELTA.patch: an ordered sequence of
+operations applied to a target document. An empty array is a valid no-op
+patch. Whether the operations actually apply to the document they target is
+a runtime question RFC 6902 leaves to the applier; structural validity here
+says nothing about it.
+"""
+
+
+class StateDeltaEvent(BaseEvent):
+    """Changes the agent state incrementally."""
+
+    type: Literal[EventType.STATE_DELTA] = EventType.STATE_DELTA
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    delta: JsonPatch
+    """
+    The change, as an RFC 6902 patch against the current state. Structural
+    validity here does not mean the patch applies: a well-formed operation
+    may point at a path that does not exist, which RFC 6902 leaves to the
+    applier.
+    """
+
+
+class DeveloperMessage(BaseMessage):
+    """Instructions from the application developer."""
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message within the conversation."""
+    role: Literal["developer"] = "developer"
+    """
+    Who the message is from. Each message definition narrows this to a
+    single value.
+    """
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """
+    A provider's opaque artefact belonging to this message, stored by a
+    consumer and returned on a later turn.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+    content: str
+    """
+    The instructions. Required: a developer message with nothing in it says
+    nothing.
+    """
+
+
+class SystemMessage(BaseMessage):
+    """Instructions from the system."""
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message within the conversation."""
+    role: Literal["system"] = "system"
+    """
+    Who the message is from. Each message definition narrows this to a
+    single value.
+    """
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """
+    A provider's opaque artefact belonging to this message, stored by a
+    consumer and returned on a later turn.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+    content: str
+    """The instructions. Required."""
+
+
+class FunctionCall(GeneratedBaseModel):
+    """The name and arguments of a tool call."""
+
+    name: str
+    """Which tool is being called."""
+    arguments: str
+    """
+    The arguments as a JSON string, not as parsed JSON. Kept as written
+    because a model can emit arguments that are not valid JSON, and losing
+    them at the protocol boundary would hide the fault from the consumer
+    that has to handle it.
+    """
+
+
+class ToolCall(GeneratedBaseModel):
+    """
+    A call an assistant message made. Carries no subagent attribution of its
+    own and inherits its containing message's, since several calls can share
+    one parent.
+    """
+
+    id: str
+    """
+    Identifies the call. The answering tool message carries this as its
+    toolCallId.
+    """
+    type: Literal["function"] = "function"
+    """The only kind of call the protocol models."""
+    function: FunctionCall
+    """What is being called, and with what."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """A provider's opaque artefact belonging to this call."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """
+    Extra information attached to this call. Carried here rather than folded
+    into the containing message, because several calls can share one parent
+    and merging them would make the result depend on their order.
+    """
+
+
+class AssistantMessage(BaseMessage):
+    """
+    A message from the agent. Content is optional because a turn may consist
+    only of tool calls.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message within the conversation."""
+    role: Literal["assistant"] = "assistant"
+    """
+    Who the message is from. Each message definition narrows this to a
+    single value.
+    """
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """
+    A provider's opaque artefact belonging to this message, stored by a
+    consumer and returned on a later turn.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+    content: Optional[str] = Field(default=None)
+    """What the agent said, if it said anything."""
+    tool_calls: Optional[List[ToolCall]] = Field(default=None)
+    """The tool calls this turn made."""
+
+
+class UserMessage(BaseMessage):
+    """A message from the person using the application."""
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message within the conversation."""
+    role: Literal["user"] = "user"
+    """
+    Who the message is from. Each message definition narrows this to a
+    single value.
+    """
+    name: Optional[str] = Field(default=None)
+    """An optional display name for the author."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """
+    A provider's opaque artefact belonging to this message, stored by a
+    consumer and returned on a later turn.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+    content: Union[str, List[ContentPart]]
+    """
+    What the person sent: either plain text, or an ordered list of parts for
+    a multimodal message.
+    """
+
+
+class ToolMessage(GeneratedBaseModel):
+    """
+    What a tool returned, as a message in the conversation. Stands alone
+    rather than composing BaseMessage, because it carries no name.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message."""
+    role: Literal["tool"] = "tool"
+    """
+    Fixed. Declared here rather than inherited, because this message does
+    not compose BaseMessage.
+    """
+    content: Union[str, List[ContentPart]]
+    """
+    What the tool returned: either plain text, or an ordered list of parts.
+    A tool returning structured data serialises it into text; media travel
+    as parts of their own.
+    """
+    tool_call_id: str
+    """The call this answers."""
+    error: Optional[str] = Field(default=None)
+    """
+    Why the tool failed, when it did. Present alongside content rather than
+    instead of it, so a partial result survives a failure.
+    """
+    encrypted_value: Optional[str] = Field(default=None)
+    """A provider's opaque artefact belonging to this message."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+
+
+class ActivityMessage(GeneratedBaseModel):
+    """
+    Structured progress that is not conversation content, materialised as a
+    message so it keeps its place in the sequence. Stands alone rather than
+    composing BaseMessage, because its content is an object rather than a
+    string.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message."""
+    role: Literal["activity"] = "activity"
+    """
+    Fixed. Declared here rather than inherited, because this message does
+    not compose BaseMessage.
+    """
+    activity_type: str
+    """
+    What kind of activity this is. An open string: the set is the
+    producer's.
+    """
+    content: Dict[str, Any]
+    """The activity's payload, open by key."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+
+
+class ReasoningMessage(GeneratedBaseModel):
+    """
+    A span of the agent's reasoning, materialised as a message. Stands alone
+    rather than composing BaseMessage, because it carries no name.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the message."""
+    role: Literal["reasoning"] = "reasoning"
+    """
+    Fixed. Declared here rather than inherited, because this message does
+    not compose BaseMessage.
+    """
+    content: str
+    """The reasoning text."""
+    encrypted_value: Optional[str] = Field(default=None)
+    """A provider's opaque reasoning artefact belonging to this message."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this message."""
+
+
+Message = Annotated[
+    Union[DeveloperMessage, SystemMessage, AssistantMessage, UserMessage, ToolMessage, ActivityMessage, ReasoningMessage],
+    Field(discriminator="role"),
+]
+"""Any message in a conversation. Discriminated by role."""
+
+
+class MessagesSnapshotEvent(BaseEvent):
+    """
+    The complete set of messages the producer owns, in order.
+    Conversation-wide rather than a plain overwrite: a consumer may keep
+    messages of its own that no producer tracks, so exactly how a snapshot
+    reconciles with those is behavioural and belongs in the prose. Being
+    conversation-wide it cannot belong to a single subagent, so it carries
+    no attribution; it does establish which subagent owns each message it
+    contains, through the messages themselves.
+    """
+
+    type: Literal[EventType.MESSAGES_SNAPSHOT] = EventType.MESSAGES_SNAPSHOT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    messages: List[Message]
+    """The messages the producer is declaring, in order."""
+
+
+class ActivitySnapshotEvent(BaseEvent):
+    """
+    Reports structured progress that is not conversation content, such as a
+    step a UI renders as its own widget.
+    """
+
+    type: Literal[EventType.ACTIVITY_SNAPSHOT] = EventType.ACTIVITY_SNAPSHOT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The activity message this describes."""
+    activity_type: str
+    """
+    What kind of activity this is. An open string: the set is the
+    producer's, not the protocol's.
+    """
+    content: Dict[str, Any]
+    """The activity's payload, open by key."""
+    replace: Optional[bool] = Field(default=None)
+    """
+    Whether this snapshot overwrites the activity's existing content. Absent
+    means it does, and that meaning is normative; only an explicit false
+    asks a consumer to leave what is already there. It does not ask for a
+    merge — ACTIVITY_DELTA is how content is changed incrementally. What a
+    consumer does with a non-overwriting snapshot is behavioural and belongs
+    in the prose.
+    """
+
+
+class ActivityDeltaEvent(BaseEvent):
+    """Changes an activity message's content incrementally."""
+
+    type: Literal[EventType.ACTIVITY_DELTA] = EventType.ACTIVITY_DELTA
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The activity message being changed."""
+    activity_type: str
+    """What kind of activity this is."""
+    patch: JsonPatch
+    """The change, as an RFC 6902 patch against the activity's content."""
+
+
+class RawEvent(BaseEvent):
+    """
+    Passes a provider-native event through untranslated, for consumers that
+    need detail the protocol does not model.
+    """
+
+    type: Literal[EventType.RAW] = EventType.RAW
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    event: Any
+    """
+    The provider's own event. Any JSON value, and required: an event whose
+    only purpose is to carry this would say nothing without it.
+    """
+    source: Optional[str] = Field(default=None)
+    """Which provider or framework the event came from."""
+
+
+class CustomEvent(BaseEvent):
+    """
+    The protocol's extension point for an application's own events. Anything
+    a consumer does with one is outside the protocol.
+    """
+
+    type: Literal[EventType.CUSTOM] = EventType.CUSTOM
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    name: str
+    """
+    What this custom event is. Required: without it a consumer cannot route
+    the value.
+    """
+    value: Any
+    """The payload. Any JSON value, and required."""
+
+
+class Tool(GeneratedBaseModel):
+    """A tool the agent may call."""
+
+    name: str
+    """The tool's name, as the agent will call it."""
+    description: str
+    """What the tool does, for the agent to decide when to use it."""
+    parameters: Optional[Any] = Field(default=None)
+    """
+    A JSON Schema describing the tool's arguments. Carried opaquely: the
+    protocol does not constrain or validate it. Optional, because all three
+    SDKs already treat it that way and a tool that takes no arguments has
+    nothing to declare; an absent schema and an empty one mean the same
+    thing to an agent.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """
+    Extra information about the tool, for consumers that attach their own
+    rendering or routing information to it.
+    """
+
+
+class Context(GeneratedBaseModel):
+    """
+    A named piece of ambient information given to the agent for the run,
+    distinct from the conversation.
+    """
+
+    description: str
+    """What this context is, for the agent to interpret."""
+    value: str
+    """The context itself."""
+
+
+class ResumeEntry(GeneratedBaseModel):
+    """An answer to one interrupt, sent on the run that continues from it."""
+
+    interrupt_id: str
+    """The interrupt being answered."""
+    status: Literal["resolved", "cancelled"]
+    """Whether the interrupt was answered or abandoned."""
+    payload: Optional[Any] = Field(default=None)
+    """The answer the agent asked for and will act on. Any JSON value."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """
+    Envelope information about the response, such as signatures or routing
+    keys, as opposed to payload, which is the answer itself.
+    """
+
+
+class RunAgentInput(GeneratedBaseModel):
+    """
+    A request to run an agent. Also echoed back as RUN_STARTED.input. Only
+    threadId, runId and messages are required: those are the three the SDKs
+    already agree on, and for tools and context an absent key and an empty
+    array mean the same thing, so requiring them would catch nothing a
+    producer could get wrong.
+    """
+
+    thread_id: str
+    """The conversation this run belongs to."""
+    run_id: str
+    """Identifies this run."""
+    protocol_version: Optional[str] = Field(default=None)
+    """
+    The protocol version this consumer speaks, such as "1.0". Absent means
+    the input was produced before the protocol carried a version — the
+    versioning rules in the prose govern what each side does with that. Sent
+    in-band rather than by the transport, so a recorded exchange stays
+    self-describing.
+    """
+    parent_run_id: Optional[str] = Field(default=None)
+    """The run that spawned this one."""
+    state: Optional[State] = Field(default=None)
+    """The state the run starts from."""
+    messages: List[Message]
+    """The conversation so far, in order."""
+    tools: Optional[List[Tool]] = Field(default=None)
+    """The tools the agent may call. Absent means none."""
+    context: Optional[List[Context]] = Field(default=None)
+    """Ambient information for the run. Absent means none."""
+    forwarded_props: Optional[Any] = Field(default=None)
+    """
+    Application-specific values passed through to the agent untouched. Any
+    JSON value.
+    """
+    resume: Optional[List[ResumeEntry]] = Field(default=None)
+    """
+    Answers to the interrupts that ended a previous run, when this run
+    continues from one.
+    """
+
+
+class RunStartedEvent(BaseEvent):
+    """Opens a run. Run-scoped, so it carries no subagent attribution."""
+
+    type: Literal[EventType.RUN_STARTED] = EventType.RUN_STARTED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    thread_id: str
+    """The conversation this run belongs to."""
+    run_id: str
+    """Identifies this run."""
+    protocol_version: Optional[str] = Field(default=None)
+    """
+    The protocol version this producer speaks, such as "1.0" — the
+    producer's own version, not an echo of the input's, which is what makes
+    the pair a negotiation: each side declares itself and the consumer sees
+    a downgrade the moment it happens. Absent means a producer from before
+    the protocol carried a version.
+    """
+    parent_run_id: Optional[str] = Field(default=None)
+    """
+    The run that spawned this one, when an agent invokes another agent as a
+    separate run rather than as a subagent within one.
+    """
+    input: Optional[RunAgentInput] = Field(default=None)
+    """
+    The request this run was started from, echoed back so a consumer that
+    did not make the request can still see what the agent was asked.
+    """
+
+
+class RunFinishedSuccessOutcome(GeneratedBaseModel):
+    """
+    The run completed. Equivalent to an absent outcome. Closed like every
+    other object, which is also what keeps it from carrying the suspended
+    sibling's interrupts — a success with an interrupt still pending would
+    be a contradiction, not an extension. A completed run may still have
+    left frontend tool calls for the application to answer;
+    pendingToolCallIds names them.
+    """
+
+    type: Literal["success"] = "success"
+    """Discriminator."""
+    pending_tool_call_ids: Optional[List[str]] = Field(default=None)
+    """
+    The tool calls this run started and left unanswered — no
+    TOOL_CALL_RESULT in the run — for the application to answer in the next
+    input's messages, in the order they were made. Absent or empty means the
+    producer named none, and a consumer derives the list from the stream;
+    otherwise it is the list, and it agrees with the stream. On the success
+    outcome rather than the event because a run that stopped on a frontend
+    tool call is a completed run: whether the application continues the
+    thread is its own decision, so the producer reports what it knows and no
+    more. Each item: A tool call id, as carried by TOOL_CALL_START.
+    """
+
+
+class Interrupt(GeneratedBaseModel):
+    """
+    Something a run needs from outside before it can continue, such as an
+    approval or a missing value.
+    """
+
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    id: str
+    """Identifies the interrupt. A resume entry answers it by this id."""
+    reason: str
+    """
+    Why the run stopped. An open string rather than an enumeration: the
+    protocol does not attempt to classify every reason an agent might need
+    input.
+    """
+    message: Optional[str] = Field(default=None)
+    """A human-readable prompt for whoever answers."""
+    tool_call_id: Optional[str] = Field(default=None)
+    """The tool call this interrupt concerns, when it is a tool approval."""
+    response_schema: Optional[Dict[str, Any]] = Field(default=None)
+    """
+    A JSON Schema describing the answer this interrupt expects, so a
+    consumer can build a form for it. Carried opaquely: the protocol does
+    not constrain or validate it. Restricted to an object because TypeScript
+    and Python both declare it that way; .NET holds it as any JSON, and the
+    ticket that commissioned this schema lists it among the arbitrary-JSON
+    fields. Following the two that constrain it keeps the schema from
+    accepting documents the reference client rejects, at the cost of
+    rejecting the boolean schemas JSON Schema also permits — a bare true for
+    "any answer". Recorded as a known divergence rather than settled.
+    """
+    expires_at: Optional[str] = Field(default=None)
+    """
+    When the interrupt stops being answerable. Deliberately unconstrained
+    rather than a date-time format, because producers already disagree about
+    the representation and tightening it here would reject streams that work
+    today. The documented convention is ISO 8601, and a consumer comparing
+    this value will parse it as a date, so a value that is not one leaves
+    the interrupt looking permanently unexpired.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this interrupt."""
+
+
+class RunFinishedInterruptOutcome(GeneratedBaseModel):
+    """
+    The run is paused, waiting for something outside it. Resuming means
+    starting a new run whose resume entries answer these interrupts.
+    """
+
+    type: Literal["interrupt"] = "interrupt"
+    """Discriminator."""
+    interrupts: List[Interrupt] = Field(min_length=1)
+    """
+    What the run is waiting for. At least one: an interrupt outcome with
+    nothing to answer would leave a consumer with nothing to do.
+    """
+
+
+class RunFinishedCancelledOutcome(GeneratedBaseModel):
+    """
+    The run was stopped before it completed, by whoever was running it, and
+    did not fail. Neither success nor interrupt: nothing was produced as a
+    result, and nothing is waited for, so the next run on the thread is an
+    ordinary new run rather than a resume. Closed like its siblings: a
+    cancelled run has no interrupts to carry. Named in the schema before 1.0
+    because an outcome a consumer does not recognise is stripped and read as
+    success — a cancellation added later would reach every 1.0 consumer as a
+    completed run.
+    """
+
+    type: Literal["cancelled"] = "cancelled"
+    """Discriminator."""
+
+
+RunFinishedOutcome = Annotated[
+    Union[RunFinishedSuccessOutcome, RunFinishedInterruptOutcome, RunFinishedCancelledOutcome],
+    Field(discriminator="type"),
+]
+"""Why a run ended."""
+
+
+class TokenUsage(GeneratedBaseModel):
+    """
+    Token counts for one provider and model, in the protocol's own
+    accounting: every count is either a total or a named part of one, so
+    entries from different providers add up without double-counting.
+    inputTokens and outputTokens are the totals; reasoningTokens,
+    cachedInputTokens and cacheWriteInputTokens are parts of them, never
+    additions to them; totalTokens is the two totals summed. Every field is
+    a label or a number — nothing content-bearing or identifying, no
+    prompts, completions, messages, or thread, run and user identifiers.
+    """
+
+    provider: Optional[str] = Field(default=None)
+    """Which provider served the request."""
+    model: Optional[str] = Field(default=None)
+    """Which model served the request."""
+    input_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Every prompt token the call was charged for: tokens read from a provider
+    cache, tokens written to one, and audio or other non-text input all
+    count here. cachedInputTokens and cacheWriteInputTokens break this
+    number down and are never added to it — a provider that reports its
+    cache counts beside a smaller input count has them added in by the
+    producer before the entry leaves. Bounded like timestamp and for the
+    same reason: a count above the JSON safe-integer range does not survive
+    a round trip, so a consumer would silently read a different number than
+    the producer wrote.
+    """
+    output_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Every generated token, reasoning included where the provider
+    distinguishes it. reasoningTokens breaks this number down and is never
+    added to it — a provider that reports reasoning tokens beside a smaller
+    completion count has them added in by the producer.
+    """
+    total_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    inputTokens plus outputTokens, under the accounting above. A producer
+    MAY compute it rather than copy a provider's total, and copies a
+    provider's total only when that total counts the same way, so a consumer
+    can read this field as the sum of the other two.
+    """
+    reasoning_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Output tokens spent on reasoning, where the provider distinguishes them.
+    Part of outputTokens, not in addition to it.
+    """
+    cached_input_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Input tokens read from a provider cache. Part of inputTokens, not in
+    addition to it, and disjoint from cacheWriteInputTokens.
+    """
+    cache_write_input_tokens: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Input tokens written to a provider cache on this call, where the
+    provider distinguishes them. Part of inputTokens, not in addition to it,
+    and disjoint from cachedInputTokens. Its own field because providers
+    price a cache write differently from a cache read, so a consumer
+    computing cost cannot do without it.
+    """
+
+
+class RunFinishedEvent(BaseEvent):
+    """
+    Closes a run that did not fail. Run-scoped, so it carries no subagent
+    attribution.
+    """
+
+    type: Literal[EventType.RUN_FINISHED] = EventType.RUN_FINISHED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    thread_id: str
+    """The conversation this run belongs to."""
+    run_id: str
+    """The run being closed."""
+    result: Optional[Any] = Field(default=None)
+    """The run's return value, if it has one. Any JSON value."""
+    outcome: Optional[RunFinishedOutcome] = Field(default=None)
+    """
+    Why the run ended. Absent means success, so every producer written
+    before outcomes existed is already conformant.
+    """
+    usage: Optional[List[TokenUsage]] = Field(default=None)
+    """
+    Token usage for the run, one entry per provider and model, so a run that
+    invoked several models keeps them separate. A consumer that only wants
+    totals sums across the entries. The run is the accounting boundary:
+    usage covers every model call made within the run, calls made by its
+    subagents included; an agent invoked as a separate run under parentRunId
+    reports its own usage on its own terminal event; and a run that resumes
+    an interrupted one reports only the calls it made itself, not the
+    interrupted run's.
+    """
+
+
+class RunErrorEvent(BaseEvent):
+    """
+    Ends a run that failed. Run-scoped, so it carries no subagent
+    attribution; a subagent that fails without ending the run reports
+    SUBAGENT_ERROR instead.
+    """
+
+    type: Literal[EventType.RUN_ERROR] = EventType.RUN_ERROR
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    message: str
+    """What went wrong, for a person to read."""
+    code: Optional[str] = Field(default=None)
+    """
+    A machine-readable error code. An open string: the protocol defines no
+    vocabulary.
+    """
+    usage: Optional[List[TokenUsage]] = Field(default=None)
+    """
+    Token usage accrued before the failure, for a run that completed one or
+    more model calls before dying. Scoped as on RUN_FINISHED: the run's own
+    calls, subagents included.
+    """
+
+
+class StepStartedEvent(BaseEvent):
+    """
+    Opens a named step within a run, for producers whose frameworks have a
+    step concept worth surfacing.
+    """
+
+    type: Literal[EventType.STEP_STARTED] = EventType.STEP_STARTED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    step_name: str
+    """
+    The step's name. Identifies it: the matching STEP_FINISHED carries the
+    same name.
+    """
+
+
+class StepFinishedEvent(BaseEvent):
+    """Closes a named step."""
+
+    type: Literal[EventType.STEP_FINISHED] = EventType.STEP_FINISHED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    step_name: str
+    """The step being closed."""
+
+
+class ReasoningStartEvent(BaseEvent):
+    """
+    Opens a span of reasoning. A span may contain several reasoning
+    messages.
+    """
+
+    type: Literal[EventType.REASONING_START] = EventType.REASONING_START
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The span being opened."""
+
+
+class ReasoningMessageStartEvent(BaseEvent):
+    """Opens a streamed reasoning message."""
+
+    type: Literal[EventType.REASONING_MESSAGE_START] = EventType.REASONING_MESSAGE_START
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The reasoning message this stream builds."""
+    role: Literal["reasoning"] = "reasoning"
+    """
+    Fixed, and required rather than defaulted. The requirement is inherited
+    from the SDKs rather than chosen.
+    """
+
+
+class ReasoningMessageContentEvent(BaseEvent):
+    """Appends a fragment to a streamed reasoning message."""
+
+    type: Literal[EventType.REASONING_MESSAGE_CONTENT] = EventType.REASONING_MESSAGE_CONTENT
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The reasoning message this fragment belongs to."""
+    delta: str
+    """The fragment to append. May be the empty string."""
+
+
+class ReasoningMessageEndEvent(BaseEvent):
+    """Closes a streamed reasoning message."""
+
+    type: Literal[EventType.REASONING_MESSAGE_END] = EventType.REASONING_MESSAGE_END
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The reasoning message being closed."""
+
+
+class ReasoningMessageChunkEvent(BaseEvent):
+    """
+    A shorthand that stands in for a reasoning message's start, content and
+    end sequence.
+    """
+
+    type: Literal[EventType.REASONING_MESSAGE_CHUNK] = EventType.REASONING_MESSAGE_CHUNK
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: Optional[str] = Field(default=None)
+    """
+    The reasoning message this chunk belongs to. Absent continues the one
+    already open.
+    """
+    delta: Optional[str] = Field(default=None)
+    """The fragment to append. May be the empty string."""
+
+
+class ReasoningEndEvent(BaseEvent):
+    """Closes a span of reasoning."""
+
+    type: Literal[EventType.REASONING_END] = EventType.REASONING_END
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    message_id: str
+    """The span being closed."""
+
+
+ReasoningEncryptedValueSubtype = Literal["tool-call", "message"]
+"""Whether a REASONING_ENCRYPTED_VALUE belongs to a message or to a tool call."""
+
+
+class ReasoningEncryptedValueEvent(BaseEvent):
+    """
+    Carries a provider's opaque, encrypted reasoning artefact, which a
+    consumer stores and returns on a later turn without being able to read
+    it.
+    """
+
+    type: Literal[EventType.REASONING_ENCRYPTED_VALUE] = EventType.REASONING_ENCRYPTED_VALUE
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation this belongs to. Absent means the parent agent
+    produced it directly.
+    """
+    subtype: ReasoningEncryptedValueSubtype
+    """
+    What kind of thing entityId names, which decides where the value is
+    stored.
+    """
+    entity_id: str
+    """
+    What the value belongs to: a message id or a tool call id, according to
+    subtype.
+    """
+    encrypted_value: str
+    """The provider's opaque artefact."""
+
+
+class SubagentStartedEvent(BaseEvent):
+    """
+    Announces that a subagent invocation has begun. Everything the subagent
+    produces afterwards is attributed by carrying its subagentRunId, so a
+    consumer can group the work without replaying the stream. Composed from
+    BaseEvent alone rather than Attributable, because here subagentRunId
+    identifies the subagent rather than attributing the event to one;
+    attribution to an enclosing subagent is parentSubagentRunId.
+    """
+
+    type: Literal[EventType.SUBAGENT_STARTED] = EventType.SUBAGENT_STARTED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: SubagentRunId
+    """The invocation being announced."""
+    name: str
+    """
+    The subagent's name, which is reusable across invocations, unlike
+    subagentRunId.
+    """
+    description: Optional[str] = Field(default=None)
+    """What this subagent is for, for a consumer to display."""
+    parent_subagent_run_id: Optional[SubagentRunId] = Field(default=None)
+    """
+    The subagent invocation that spawned this one, for nested delegation.
+    Absent means the parent agent spawned it directly.
+    """
+    parent_tool_call_id: Optional[str] = Field(default=None)
+    """
+    The tool call that spawned this subagent, for the pattern where agents
+    are exposed to a model as tools. Lets a consumer tie the subagent to the
+    call without reading rawEvent.
+    """
+    parent_message_id: Optional[str] = Field(default=None)
+    """The message that held the spawning tool call."""
+
+
+class SubagentFinishedSuccessOutcome(GeneratedBaseModel):
+    """The subagent completed its work. Equivalent to an absent outcome."""
+
+    type: Literal["success"] = "success"
+    """Discriminator."""
+
+
+class SubagentFinishedSuspendedOutcome(GeneratedBaseModel):
+    """
+    The subagent is paused awaiting outside input. Terminal for this stream,
+    not for the subagent: a later run may continue the same invocation once
+    the interrupts are answered.
+    """
+
+    type: Literal["suspended"] = "suspended"
+    """Discriminator."""
+    interrupt_ids: Optional[List[str]] = Field(default=None)
+    """
+    The run-level interrupts this subagent raised itself. May be empty or
+    absent: a subagent suspended because a descendant interrupted owns no
+    interrupt of its own. Each item: An Interrupt.id.
+    """
+
+
+SubagentFinishedOutcome = Annotated[
+    Union[SubagentFinishedSuccessOutcome, SubagentFinishedSuspendedOutcome],
+    Field(discriminator="type"),
+]
+"""
+Why a subagent's segment of a run ended. Mirrors RunFinishedOutcome one
+level down.
+"""
+
+
+class SubagentFinishedEvent(BaseEvent):
+    """
+    Ends a subagent invocation's segment of this run, either because the
+    work completed or because it is suspended awaiting outside input.
+    """
+
+    type: Literal[EventType.SUBAGENT_FINISHED] = EventType.SUBAGENT_FINISHED
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: SubagentRunId
+    """The invocation being closed."""
+    result: Optional[Any] = Field(default=None)
+    """
+    The subagent's return value, if it has one. Any JSON value, mirroring
+    RUN_FINISHED.result.
+    """
+    outcome: Optional[SubagentFinishedOutcome] = Field(default=None)
+    """
+    Why the segment ended. Absent means success. A suspended subagent is
+    neither a success nor a failure, which is why saying so needs its own
+    value rather than being inferred from a later interrupt.
+    """
+
+
+class SubagentErrorEvent(BaseEvent):
+    """
+    Reports that a subagent invocation failed. The run may continue: a
+    parent agent is free to handle a failed subagent, which is why this is
+    not RUN_ERROR.
+    """
+
+    type: Literal[EventType.SUBAGENT_ERROR] = EventType.SUBAGENT_ERROR
+    """
+    Which event this is. Each event definition narrows this to a single
+    value.
+    """
+    timestamp: Optional[int] = Field(default=None, ge=-9007199254740991, le=9007199254740991)
+    """
+    When the event was created. Bounded to the range JSON numbers survive a
+    round trip in, so the value a consumer reads is the value the producer
+    wrote. Deliberately not a float. The unit is not constrained here,
+    because it never has been stated normatively; every SDK that sets it in
+    practice uses milliseconds since the Unix epoch, and a producer choosing
+    another unit will be misread by consumers even though it validates.
+    Nothing in the protocol computes with this value.
+    """
+    raw_event: Optional[Any] = Field(default=None)
+    """
+    The provider-native event this one was translated from, carried verbatim
+    for debugging and for consumers that need detail the protocol does not
+    model. Any JSON value.
+    """
+    metadata: Optional[Metadata] = Field(default=None)
+    """Extra information attached to this event."""
+    subagent_run_id: SubagentRunId
+    """The invocation that failed."""
+    message: str
+    """What went wrong, for a person to read."""
+    code: Optional[str] = Field(default=None)
+    """A machine-readable error code. An open string."""
+
+
+Event = Annotated[
+    Union[TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, TextMessageChunkEvent, ToolCallStartEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallChunkEvent, ToolCallResultEvent, StateSnapshotEvent, StateDeltaEvent, MessagesSnapshotEvent, ActivitySnapshotEvent, ActivityDeltaEvent, RawEvent, CustomEvent, RunStartedEvent, RunFinishedEvent, RunErrorEvent, StepStartedEvent, StepFinishedEvent, ReasoningStartEvent, ReasoningMessageStartEvent, ReasoningMessageContentEvent, ReasoningMessageEndEvent, ReasoningMessageChunkEvent, ReasoningEndEvent, ReasoningEncryptedValueEvent, SubagentStartedEvent, SubagentFinishedEvent, SubagentErrorEvent],
+    Field(discriminator="type"),
+]
+"""
+Any AG-UI event. Every member is normative: there is no optional tier and no
+event a consumer may decline to implement. Discriminated by the type
+property.
+"""
+
+
+Role = Literal["developer", "system", "assistant", "user", "tool", "activity", "reasoning"]
+"""Every role a materialised message may have."""
+
+
+class SubagentInfo(GeneratedBaseModel):
+    """Describes a subagent that can be invoked by a parent agent."""
+
+    name: str
+    """Unique name or identifier of the subagent."""
+    description: Optional[str] = Field(default=None)
+    """
+    What this subagent specializes in. Helps clients build agent selection
+    UIs.
+    """
+
+
+class IdentityCapabilities(GeneratedBaseModel):
+    """
+    Basic metadata about the agent. Useful for discovery UIs, agent
+    marketplaces, and debugging. Set these when you want clients to display
+    agent information or when multiple agents are available and users need
+    to pick one.
+    """
+
+    name: Optional[str] = Field(default=None)
+    """Human-readable name shown in UIs and agent selectors."""
+    type: Optional[str] = Field(default=None)
+    """
+    The framework or platform powering this agent (e.g., "langgraph",
+    "mastra", "crewai").
+    """
+    description: Optional[str] = Field(default=None)
+    """
+    What this agent does — helps users and routing logic decide when to use
+    it.
+    """
+    version: Optional[str] = Field(default=None)
+    """
+    Semantic version of the agent (e.g., "1.2.0"). Useful for compatibility
+    checks.
+    """
+    provider: Optional[str] = Field(default=None)
+    """Organization or team that maintains this agent."""
+    documentation_url: Optional[str] = Field(default=None)
+    """URL to the agent's documentation or homepage."""
+    metadata: Optional[Metadata] = Field(default=None)
+    """Arbitrary key-value pairs for integration-specific identity info."""
+
+
+class TransportCapabilities(GeneratedBaseModel):
+    """
+    Declares which transport mechanisms the agent supports. Clients use this
+    to pick the best connection strategy. Only set flags to true for
+    transports your agent actually handles — omit or set false for
+    unsupported ones.
+    """
+
+    streaming: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent streams responses via SSE. Most agents enable
+    this.
+    """
+    websocket: Optional[bool] = Field(default=None)
+    """Set true if the agent accepts persistent WebSocket connections."""
+    http_binary: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent supports the AG-UI binary protocol (protobuf over
+    HTTP).
+    """
+    push_notifications: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can send async updates via webhooks after a run
+    finishes.
+    """
+    resumable: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent supports resuming interrupted streams via sequence
+    numbers.
+    """
+
+
+class ToolsCapabilities(GeneratedBaseModel):
+    """
+    Tool calling capabilities. Distinguishes between tools the agent itself
+    provides (listed in items) and tools the client passes at runtime via
+    RunAgentInput.tools. Enable this when your agent can call functions,
+    search the web, execute code, etc.
+    """
+
+    supported: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can make tool calls at all. Set false to
+    explicitly signal tool calling is disabled even if items are present.
+    """
+    items: Optional[List[Tool]] = Field(default=None)
+    """
+    The tools this agent provides on its own (full JSON Schema definitions).
+    These are distinct from client-provided tools passed in
+    RunAgentInput.tools.
+    """
+    parallel_calls: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can invoke multiple tools concurrently within a
+    single step.
+    """
+    client_provided: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent accepts and uses tools provided by the client at
+    runtime.
+    """
+
+
+class OutputCapabilities(GeneratedBaseModel):
+    """
+    Output format support. Enable structuredOutput when your agent can
+    return responses conforming to a JSON schema, which is useful for
+    programmatic consumption.
+    """
+
+    structured_output: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can produce structured JSON output matching a
+    provided schema.
+    """
+    supported_mime_types: Optional[List[str]] = Field(default=None)
+    """
+    MIME types the agent can produce (e.g., ["text/plain",
+    "application/json"]). Omit if the agent only produces plain text.
+    """
+
+
+class StateCapabilities(GeneratedBaseModel):
+    """
+    State and memory management capabilities. These tell the client how the
+    agent handles shared state and whether conversation context persists
+    across runs.
+    """
+
+    snapshots: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent emits STATE_SNAPSHOT events (full state
+    replacement).
+    """
+    deltas: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent emits STATE_DELTA events (JSON Patch incremental
+    updates).
+    """
+    memory: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent has long-term memory beyond the current thread
+    (e.g., vector store, knowledge base, or cross-session recall).
+    """
+    persistent_state: Optional[bool] = Field(default=None)
+    """
+    Set true if state is preserved across multiple runs within the same
+    thread. When false, state resets on each run.
+    """
+
+
+class MultiAgentCapabilities(GeneratedBaseModel):
+    """
+    Multi-agent coordination capabilities. Enable these when your agent can
+    orchestrate or hand off work to other agents.
+    """
+
+    supported: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent participates in any form of multi-agent
+    coordination.
+    """
+    delegation: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can delegate subtasks to other agents while
+    retaining control.
+    """
+    handoffs: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can transfer the conversation entirely to another
+    agent.
+    """
+    subagents: Optional[List[SubagentInfo]] = Field(default=None)
+    """
+    List of subagents this agent can invoke. Helps clients build agent
+    selection UIs.
+    """
+
+
+class ReasoningCapabilities(GeneratedBaseModel):
+    """
+    Reasoning and thinking capabilities. Enable these when your agent
+    exposes its internal thought process (e.g., chain-of-thought, extended
+    thinking).
+    """
+
+    supported: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent produces reasoning/thinking tokens visible to the
+    client.
+    """
+    streaming: Optional[bool] = Field(default=None)
+    """
+    Set true if reasoning tokens are streamed incrementally (vs. returned
+    all at once).
+    """
+    encrypted: Optional[bool] = Field(default=None)
+    """
+    Set true if reasoning content is encrypted (zero-data-retention mode).
+    Clients should expect opaque encryptedValue fields instead of readable
+    content.
+    """
+
+
+class MultimodalInputCapabilities(GeneratedBaseModel):
+    """
+    Modalities the agent can accept as input. Clients use this to show or
+    hide file upload buttons, audio recorders, image pickers, etc.
+    """
+
+    image: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can process image inputs (e.g., screenshots,
+    photos).
+    """
+    audio: Optional[bool] = Field(default=None)
+    """Set true if the agent can process audio inputs (speech, recordings)."""
+    video: Optional[bool] = Field(default=None)
+    """Set true if the agent can process video inputs."""
+    pdf: Optional[bool] = Field(default=None)
+    """Set true if the agent can process PDF documents."""
+    file: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can process arbitrary file uploads: files of a
+    kind the image, audio, video and document parts do not cover. Says
+    nothing about how a file arrives; a part's source (inline, URL or
+    provider handle) is a separate question.
+    """
+
+
+class MultimodalOutputCapabilities(GeneratedBaseModel):
+    """
+    Modalities the agent can produce as output. Clients use this to
+    anticipate rich content in the agent's response.
+    """
+
+    image: Optional[bool] = Field(default=None)
+    """Set true if the agent can generate images as part of its response."""
+    audio: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can produce audio output (text-to-speech, audio
+    files).
+    """
+
+
+class MultimodalCapabilities(GeneratedBaseModel):
+    """
+    Multimodal input and output support. Organized into input and output
+    sub-objects so clients can independently query what the agent accepts
+    versus what it produces.
+    """
+
+    input: Optional[MultimodalInputCapabilities] = Field(default=None)
+    """
+    Modalities the agent can accept as input (images, audio, video, PDFs,
+    files).
+    """
+    output: Optional[MultimodalOutputCapabilities] = Field(default=None)
+    """Modalities the agent can produce as output (images, audio)."""
+
+
+class ExecutionCapabilities(GeneratedBaseModel):
+    """
+    Execution control and limits. Declare these so clients can set
+    expectations about how long or how many steps an agent run might take.
+    """
+
+    code_execution: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can execute code (e.g., Python, JavaScript) during
+    a run.
+    """
+    sandboxed: Optional[bool] = Field(default=None)
+    """
+    Set true if code execution happens in a sandboxed or isolated
+    environment. Only meaningful when codeExecution is true.
+    """
+    max_iterations: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Maximum number of tool-call/reasoning iterations the agent will perform
+    per run. Helps clients display progress or set timeout expectations.
+    """
+    max_execution_time: Optional[int] = Field(default=None, ge=0, le=9007199254740991)
+    """
+    Maximum wall-clock time (in milliseconds) the agent will run before
+    timing out.
+    """
+
+
+class HumanInTheLoopCapabilities(GeneratedBaseModel):
+    """
+    Human-in-the-loop interaction support. Enable these when your agent can
+    pause execution to request human input, approval, or feedback before
+    continuing.
+    """
+
+    supported: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent supports any form of human-in-the-loop
+    interaction.
+    """
+    approvals: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can pause and request explicit approval before
+    performing sensitive actions (e.g., sending emails, deleting data).
+    """
+    interventions: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent allows humans to intervene and modify its plan
+    mid-execution.
+    """
+    feedback: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent can incorporate user feedback (thumbs up/down,
+    corrections) to improve its behavior within the current session.
+    """
+    interrupts: Optional[bool] = Field(default=None)
+    """
+    Set true if the agent participates in the AG-UI interrupt protocol: it
+    ends a run with RUN_FINISHED carrying an interrupt outcome, and accepts
+    the answers back in RunAgentInput.resume.
+    """
+    approve_with_edits: Optional[bool] = Field(default=None)
+    """
+    Set true if tool-call interrupts accept editedArgs in the resume
+    payload. Only meaningful when interrupts is true.
+    """
+
+
+class AgentCapabilities(GeneratedBaseModel):
+    """
+    A typed, categorized snapshot of an agent's current capabilities. All
+    fields are optional — agents only declare what they support. An omitted
+    field means the capability is not declared (unknown), not that it is
+    unsupported. The custom field is an escape hatch for
+    integration-specific capabilities that do not fit into the standard
+    categories.
+    """
+
+    identity: Optional[IdentityCapabilities] = Field(default=None)
+    """Agent identity and metadata."""
+    transport: Optional[TransportCapabilities] = Field(default=None)
+    """Supported transport mechanisms (SSE, WebSocket, binary, etc.)."""
+    tools: Optional[ToolsCapabilities] = Field(default=None)
+    """Tools the agent provides and tool calling configuration."""
+    output: Optional[OutputCapabilities] = Field(default=None)
+    """Output format support (structured output, MIME types)."""
+    state: Optional[StateCapabilities] = Field(default=None)
+    """State and memory management (snapshots, deltas, persistence)."""
+    multi_agent: Optional[MultiAgentCapabilities] = Field(default=None)
+    """Multi-agent coordination (delegation, handoffs, subagents)."""
+    reasoning: Optional[ReasoningCapabilities] = Field(default=None)
+    """Reasoning and thinking support (chain-of-thought, encrypted thinking)."""
+    multimodal: Optional[MultimodalCapabilities] = Field(default=None)
+    """Multimodal input/output support (images, audio, video, files)."""
+    execution: Optional[ExecutionCapabilities] = Field(default=None)
+    """Execution control and limits (code execution, timeouts, iteration caps)."""
+    human_in_the_loop: Optional[HumanInTheLoopCapabilities] = Field(default=None)
+    """Human-in-the-loop support (approvals, interventions, feedback)."""
+    custom: Optional[Dict[str, Any]] = Field(default=None)
+    """
+    Integration-specific capabilities not covered by the standard
+    categories. Open by key: any JSON value is allowed under a key, because
+    the categories above cannot anticipate what an integration declares.
+    """
+
+