How to obtain conversation history with AgentFrameworkWorkflow?

[mjod]

Hi team! 👋

I'm working with AgentFrameworkWorkflow (rc8) and trying to understand the
recommended pattern for obtaining conversation history during active runs.

What I've Observed

With AgentFrameworkAgent:

• ✅ Emits MessagesSnapshotEvent at end of run (agent_run.py:2286)
• ✅ Clients receive conversation state during active runs

With AgentFrameworkWorkflow:

• ❌ Does NOT emit MessagesSnapshotEvent during runs
• ✅ AGUIThreadSnapshot stores messages internally
• ✅ Messages only emitted during hydration (empty messages array)

My Questions

1. Is this difference intentional?

   • Should workflows use a different pattern than agents for conversation state?

2. What's the recommended approach for workflow-based clients?

   • Parse executor data from ActivitySnapshotEvent? (I see full_conversation in some executor completions)
   • Reconstruct from streaming events (TEXT_MESSAGE_, TOOL_CALL_, etc.)?
   • Rely solely on hydration + AGUIThreadSnapshot?
   • Manually emit MessagesSnapshotEvent in application code?

3. For AG-UI clients expecting MessagesSnapshotEvent:

   • Should workflows also emit this event like agents do?
   • Or should clients adapt to use hydration-only pattern?

Current Workaround

Currently manually emitting MessagesSnapshotEvent after RUN_FINISHED by
accumulating messages during the workflow run, but I'm wondering if there's a
built-in pattern I'm missing or if this is the intended approach.

Context

• Version: 1.0.0rc8
• Using: AgentFrameworkWorkflow with custom executors
• Observing: Some executor ActivitySnapshotEvent data includes conversation, but this seems executor-specific

Relevant Code References

• Agent emission: _agent_run.py:2286
• Workflow snapshot builder: _workflow.py:354-404
• Hydration emission: _workflow.py:216

Any guidance on the canonical pattern would be greatly appreciated! 🙏

[Mordris]

Short version: Yes, the difference is intentional in the current design — workflows route conversation history through snapshot persistence + hydration, not through an in-run MESSAGES_SNAPSHOT. But there's an important catch that likely explains your "empty array": the workflow snapshot builder only captures text / tool-call / tool-result events. Custom executors that emit structured (non-text) output produce CUSTOM (workflow_output) events, which are not folded into the snapshot's messages — so history comes back with only the user turn.

On your specific observations (all accurate): agents emit MESSAGES_SNAPSHOT right before RUN_FINISHED (_agent_run.py:2286); run_workflow_stream never does; the only workflow emission is on hydration (_workflow.py:216), gated on a non-empty snapshot.messages. During a live run the history is instead reconstructed by _WorkflowSnapshotBuilder and saved to the AGUIThreadSnapshotStore (_workflow.py:354-395). This is pinned by the golden tests (test_scenario_workflow.py vs test_scenario_agentic_chat.py), so it's by-design, not incidental.

Evaluating your four candidate approaches:

1. Parse ActivitySnapshotEvent / full_conversation — full_conversation is a field on AgentExecutorResponse (the output of an AgentExecutor), which is why you only see it in AgentExecutor completions — it rides in as raw data inside that executor's ActivitySnapshotEvent. For a graph built from AgentExecutors it genuinely holds the full conversation (per its docstring: "prior inputs + all assistant/tool outputs"), so it's a legitimate source there. The caveats: it's executor-specific (arbitrary custom executors don't produce it), and it arrives as opaque activity data rather than as protocol messages — so it's not a general/canonical history channel.
2. Reconstruct from streaming events (TEXT_MESSAGE_*, TOOL_CALL_*) — this is the correct in-connection answer, and it's what a standard AG-UI client (and the framework's own workflow demo, which configures no store) already does.
3. Hydration + AGUIThreadSnapshot — the correct cross-connection / re-sync answer, but subject to the caveat above: only text/tool events are captured. To persist a custom executor's result as conversation, have it emit assistant text (via ctx.yield_output("…") or an AgentResponse) rather than a bare dict, or map it to a Message.
4. Manually emit MESSAGES_SNAPSHOT — fine, but it must precede RUN_FINISHED. Emitting it after is rejected by AG-UI's verifyEvents (in the ag-ui-protocol/ag-ui SDK, verify.ts: "The run has already finished … Start a new run with 'RUN_STARTED'"). Your current workaround emits it after RUN_FINISHED, so a strict client (CopilotKit) will drop or error on it — worth moving ahead of the terminal event, e.g. by overriding run() and yielding the snapshot before the stream's RUN_FINISHED.

Recommended pattern: in-connection, accumulate from the streamed events (option 2); across connections, configure add_agent_framework_fastapi_endpoint(..., snapshot_store=..., snapshot_scope_resolver=...) and rely on hydration (option 3), making sure executor outputs that should count as history are emitted as text/messages so the builder captures them.

(Aside: workflow checkpointing — #6632 / PR #6646 — is a separate mechanism for resumable execution state and is explicitly independent of thread-snapshot history.)

(Edited to correct one attribution: full_conversation lives on AgentExecutorResponse, not on a request-info message as originally written.)