Skip to content

Python: [Bug]: agent-framework-ag-ui doesn't support ag-ui-protocol 1.0 #9377

Description

@mme

Observed Behavior

agent-framework-ag-ui 1.5.1 requires ag-ui-protocol>=0.1.19,<0.2, so it can't be installed alongside AG-UI 1.0 (ag-ui-protocol 1.0.0, released 2026-09). With 1.0 installed anyway, the package's own test suite has 24 failures, and several user-facing paths break:

  • Snapshot replay fails. MESSAGES_SNAPSHOT carries media as legacy binary parts, which 1.0 rejects, so replaying a thread with an image raises a ValidationError (see below). This also affects threads saved before an upgrade.
  • RUN_STARTED doesn't declare the protocol version. AG-UI 1.0 requires protocolVersion on RUN_STARTED; 1.0 clients treat the stream as an older-protocol producer.
  • Media in tool results is lost. A 1.0 tool message whose content is a ContentPart[] with an image becomes a function result holding the string form of the raw parts list, so the image never reaches the model as media.
  • A 1.0 file source is dropped silently. A part with {"type": "file", "value": "file-abc", "provider": "openai"} carries its handle in value, which isn't read, so the part disappears instead of getting the existing "unresolved reference" rejection that id sources get.

Expected Behavior

The package installs and works with ag-ui-protocol 1.x as well as 0.1.x: snapshots replay, RUN_STARTED declares protocolVersion when the SDK has one, tool-result media reaches the function result, and a file source is rejected like an id reference.

Steps to Reproduce

  1. In python/, sync the workspace and install ag-ui-protocol==1.0.0 into the environment.
  2. Run pytest packages/ag-ui/tests (24 failures), or the snippet below.

Minimal Reproduction

import asyncio
from agent_framework_ag_ui._snapshot_session import ThreadSnapshotSession
from agent_framework_ag_ui._snapshots import AGUIThreadSnapshot

stored = AGUIThreadSnapshot(messages=[{"id": "u1", "role": "user", "content": [
    {"type": "text", "text": "look"},
    {"type": "binary", "url": "https://example.com/cat.png", "mimeType": "image/png"}]}])

async def replay():
    session = ThreadSnapshotSession(store=None, scope=None, thread_id="t", stored=stored)
    return [e async for e in session.hydrate_events(run_id="r")]

asyncio.run(replay())

Error Messages and Stack Traces

pydantic_core._pydantic_core.ValidationError: 2 validation errors for MessagesSnapshotEvent
messages.0.user.content.str
  Input should be a valid string [type=string_type, ...]
messages.0.user.content.list[tagged-union[TextPart,ImagePart,AudioPart,VideoPart,DocumentPart]].1
  Input tag 'binary' found using 'type' does not match any of the expected tags: 'text', 'image', 'audio', 'video', 'document' [type=union_tag_invalid, ...]

Package Versions

agent-framework-ag-ui 1.5.1 (and main), ag-ui-protocol 1.0.0

Python Version

3.12

Operating System

macOS

Regression

No. 1.0 support is new.

I have a fix with tests ready and will open a PR referencing this issue.

Activity

  1. added
    pythonUsage: [Issues, PRs], Target: Python
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Oct 14, 2026
  2. added
    ag-uiUsage: [Issues, PRs], Target: AG-UI protocol integration
    on Oct 14, 2026
  3. changed the issue type fromtoon Oct 14, 2026
  4. removed
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Oct 14, 2026
  5. eavanvalkenburg commented on Nov 3, 2026

    @eavanvalkenburg
    Member

    /plan Coordinate the previously reviewed AG-UI protocol 1.0 support direction with the preserved work in closed/unmerged #9378, without reopening it or starting competing implementation. The maintainer closure was for unresolved outbound client protocolVersion and durable dependency-range coverage, not a rejection of first-party support. Current main still declares ag-ui-protocol >=0.1.19,<0.2; forced 1.0 installation is not a supported-version bug. Establish the remaining compatibility/migration scope for the intended 0.1.x plus 1.x range: producer RUN_STARTED and consumer RunAgentInput version declaration when supported, omission on legacy SDK, native multimedia/tool-result conversion, existing persisted binary snapshots, and explicit unresolved provider-file reference errors. Require a durable floor/latest-0.1/1.0 dependency test matrix and HTTP payload assertions, not just a lock resolved to 1.0 or historical local runs. Reuse the existing media work and completed review findings; validate latest code rather than repeat stale fixed findings. Confirm public API/default behavior and stored-thread compatibility before widening dependencies. No issue-ready label, new assignment, PR reopening or implementation/timing commitment is implied; keep the current closed-PR blockers visible.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

ag-uiUsage: [Issues, PRs], Target: AG-UI protocol integrationpythonUsage: [Issues, PRs], Target: Python

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions