Repository navigation
Open
Labels
ag-uiUsage: [Issues, PRs], Target: AG-UI protocol integrationUsage: [Issues, PRs], Target: AG-UI protocol integrationpythonUsage: [Issues, PRs], Target: PythonUsage: [Issues, PRs], Target: Python
Description
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_SNAPSHOTcarries media as legacybinaryparts, which 1.0 rejects, so replaying a thread with an image raises aValidationError(see below). This also affects threads saved before an upgrade. - RUN_STARTED doesn't declare the protocol version. AG-UI 1.0 requires
protocolVersiononRUN_STARTED; 1.0 clients treat the stream as an older-protocol producer. - Media in tool results is lost. A 1.0 tool message whose
contentis aContentPart[]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 invalue, which isn't read, so the part disappears instead of getting the existing "unresolved reference" rejection thatidsources 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
- In
python/, sync the workspace and installag-ui-protocol==1.0.0into the environment. - 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.
Metadata
Metadata
Labels
ag-uiUsage: [Issues, PRs], Target: AG-UI protocol integrationUsage: [Issues, PRs], Target: AG-UI protocol integrationpythonUsage: [Issues, PRs], Target: PythonUsage: [Issues, PRs], Target: Python
Type
Projects
- StatusShow more project fieldsNo status
Activity
eavanvalkenburg commentedon Nov 3, 2026
/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.