The conversation_id docstring entry was added here, but conversation_id is not in the function signature of handle_ag_ui_request. Same issue with run_ag_ui below (line 164). Either add the parameter to both signatures and forward it through, or remove these docstring entries.

🔴 handle_ag_ui_request documents conversation_id but lacks the parameter

The handle_ag_ui_request convenience function documents conversation_id in its docstring (pydantic_ai_slim/pydantic_ai/ag_ui.py:87) but the parameter is missing from the function signature (lines 53-72) and is not passed through to AGUIAdapter.dispatch_request() (lines 106-125). Users who follow the docstring and try to pass conversation_id='my-id' will get an unexpected keyword argument error.

The handle_ag_ui_request function in pydantic_ai_slim/pydantic_ai/ag_ui.py documents conversation_id in its docstring (line 87) but the parameter is missing from the function signature (lines 53-72). It also needs to be forwarded to AGUIAdapter.dispatch_request() in the call at lines 106-125. The fix requires adding conversation_id: str | None = None to the function signature (after deferred_tool_results), and adding conversation_id=conversation_id to the dispatch_request() call. The same issue exists for the run_ag_ui function (lines 128-206) which also documents conversation_id in its docstring (line 164) but is missing it from its signature and does not pass it to adapter.run_stream().

Was this helpful? React with 👍 or 👎 to provide feedback.

🔴 run_ag_ui documents conversation_id but lacks the parameter

The run_ag_ui function documents conversation_id in its docstring (pydantic_ai_slim/pydantic_ai/ag_ui.py:164) but the parameter is missing from the function signature (lines 128-148) and is not passed to adapter.run_stream() (lines 192-206). Users who follow the docstring and try to pass conversation_id='my-id' will get an unexpected keyword argument error.

The run_ag_ui function in pydantic_ai_slim/pydantic_ai/ag_ui.py documents conversation_id in its docstring (line 164) but the parameter is missing from the function signature (lines 128-148). It also needs to be forwarded to adapter.run_stream() in the call at lines 192-206. The fix requires adding conversation_id: str | None = None to the function signature (after deferred_tool_results on line 137), and adding conversation_id=conversation_id to the adapter.run_stream() call.

Was this helpful? React with 👍 or 👎 to provide feedback.

Consider using Literal['new'] more precisely in the public API parameter type. The conversation_id parameter across Agent.run etc. is typed str | None, which means the 'new' sentinel is valid but not discoverable from the type signature. A more self-documenting type would be something like str | Literal['new'] | None (even though Literal['new'] is a subtype of str, the union still serves as documentation for IDE autocomplete and hover docs).

@DouweM — this is an API design choice worth considering: str | None is simpler but makes users rely on reading docs to discover 'new', while a Literal['new'] union makes it visible in type hints.

Bug: further down in this method's on_complete callback (around line 780), a ModelRequest is constructed with run_id=graph_ctx.state.run_id but is missing conversation_id=graph_ctx.state.conversation_id:

messages.append(
    _messages.ModelRequest(
        parts, run_id=graph_ctx.state.run_id, timestamp=_utils.now_utc()
    )
)

Compare with _agent_graph.py _handle_final_result which correctly includes conversation_id. Messages appended via the run_stream path will silently lack the conversation ID, breaking the invariant that all messages produced during a run carry it.

The CONVERSATION_ID_BAGGAGE_KEY is read from baggage in get_agent_run_baggage_attributes() below (lines 28–30), but it's never set in the baggage. In agent/__init__.py around line 1190, baggage is set for gen_ai.agent.name and gen_ai.agent.call.id but not for gen_ai.conversation.id. This means get_agent_run_baggage_attributes() will never return a conversation_id — the read side exists but the write side is missing. Either add _otel_set_baggage(CONVERSATION_ID_BAGGAGE_KEY, state.conversation_id) alongside the other two, or remove the dead read code here.

🚩 run_ag_ui body likely also needs conversation_id forwarding

Beyond the signature bug reported in BUG-0002, the run_ag_ui function (starting at line 128) constructs an AGUIAdapter directly and calls run_stream on it. The conversation_id parameter needs to be forwarded not just through the signature but also into the adapter's run_stream call in the function body. The reviewer should verify the full function body when applying the fix to ensure end-to-end propagation.

(Refers to lines 128-148)

Was this helpful? React with 👍 or 👎 to provide feedback.

The conversation_id docstring entry documents a parameter that doesn't exist in the function signature of handle_ag_ui_request. The same issue applies to run_ag_ui below (line 164).

Since AGUIAdapter already auto-populates conversation_id from RunAgentInput.threadId (via the conversation_id property), users of these convenience functions get it for free and don't need to pass it. Either add the parameter to the signatures and forward it (for users who want to override the AG-UI threadId), or remove these docstring entries to avoid confusion.

Link to the Logfire.md docs

I don't love making new a special value, although we do that with auto in other places. Any better ideas to comunicate this without adding an extra arg which I don't wanna do?

Just say "UI adapters" and link to the overview page.