Protocol extension: explicit session sync without LLM invocation

[vmatic]

Summary

Add a run_mode field to RunAgentInput with a "sync" value that signals the backend to restore and emit session state (STATE_SNAPSHOT + MESSAGES_SNAPSHOT) without invoking the LLM. This enables session restoration on page load and explicit mid-session state refresh — both common operations that today have no first-class protocol support.

Problem

When a user returns to an existing session (page reload, new tab, device switch), the frontend has a threadId but no local state. To restore session state and message history, it currently has to trigger a full agent run. That is wasteful and incorrect: the LLM gets invoked on what is semantically a read operation, and users see a response they did not ask for.

We worked around this in our own deployment by monkey-patching ag-ui-adk to skip the LLM call when the last message is empty. That workaround is implicit, fragile, and invisible to anyone reading the call site. It should not be necessary.

We have also seen developers implement a dedicated out-of-band endpoint (e.g. GET /thread/{threadId}) as an alternative. That approach works but bypasses the existing protocol flow entirely — the client ends up with two separate integration points and the state has to be reconciled outside of the protocol. The protocol already has the right built-in mechanism for this: STATE_SNAPSHOT and MESSAGES_SNAPSHOT. What is missing is a way to invoke that mechanism without triggering an LLM call.

We haven't found a first-class way to achieve this in the current protocol — if we've missed something, we'd welcome a pointer. If there genuinely isn't one, we'd like to propose adding it.

Proposed change

Add an optional run_mode field to RunAgentInput:

export const RunAgentInputSchema = z.object({
  // ...existing fields unchanged...
  run_mode: z.enum(["run", "sync"]).optional(), // default: "run"
});

When run_mode is "sync":

• The backend reads the existing session for threadId
• Emits STATE_SNAPSHOT and MESSAGES_SNAPSHOT with the current session contents
• Emits RUN_FINISHED — keeping the standard RUN_STARTED / RUN_FINISHED envelope so clients need no special transport handling
• Does not invoke the LLM
• If no session exists yet for threadId, responds with empty state (not an error)

Precedent

The resume field added for interrupt/human-in-the-loop flows is the closest analogue — it also represents a "run" where the protocol semantics differ from a fresh LLM turn. run_mode: "sync" follows the same pattern of extending RunAgentInput rather than adding a new message type.

CopilotKit implications (out of scope for the protocol itself, noting for discussion)

For the feature to be ergonomic end-to-end, CopilotKit would benefit from:

• autoSync prop on <CopilotKit> (default true when threadId is provided) — fires a sync run on mount and whenever threadId changes
• sync() function from a hook for explicit calls (e.g. a "refresh" button)

Raising here in case the maintainers want to coordinate. Happy to track this separately if preferred.

Open questions for maintainers

1. Is extending RunAgentInput the right place, or would a separate input event type be preferable?
2. Should the RUN_STARTED / RUN_FINISHED envelope still wrap a sync response, or would a lighter-weight response shape make more sense?
3. Is run_mode the right name, or does something like intent: "sync" | "run" fit the protocol vocabulary better?
4. Are there existing discussions or in-progress work in this direction we should be aware of?

[uesleilima]

Strong +1 on the problem statement. Invoking the LLM (or even starting a full agent run) just to hydrate a thread on page load is the wrong tool.

What we shipped (and how it relates to the protocol)

We solved this with a dedicated out-of-band read, not run_mode on RunAgentInput:

• POST /agents/{name}/state returning threadId, threadExists, JSON-encoded state + messages (AG-UI message shape)
• inspired directly by the ag-ui-adk experimental /agents/state route — we generalized that pattern for a LangGraph-backed agent rather than inventing a new shape from scratch

That endpoint is not part of the AG-UI core protocol. It is an application/transport convenience that happens to speak AG-UI message/state types. Clients therefore have two integration points (run stream + state read), which is exactly the downside you call out.

We also expose a live activeRunId on that state response so a returning client can decide whether to reattach to an in-flight run. Reattach itself is another non-protocol convention today (forwardedProps.reattach on the normal run POST) — related to the hollow resumable flag discussed in #2161.

On run_mode: "sync"

I like the idea of a first-class protocol intent for this. A few preferences from having lived with the ADK-inspired endpoint:

1. Extending RunAgentInput (as you propose) keeps one client entrypoint — good for SDKs that only know run().
2. Keep the RUN_STARTED / snapshot / RUN_FINISHED envelope so existing clients need no special transport handling.
3. Naming: run_mode / intent both work; whatever lands, please make "no LLM / no graph step execution" an explicit guarantee in the spec text.
4. Consider how sync interacts with in-flight durable runs — a sync that only returns checkpoint history while a run is still producing events needs a clear story (e.g. also surface an active runId, or define sync as checkpoint-only).

If core adopts sync, we'd treat our /state route as a compatibility shim and prefer the protocol path for new clients. Until then, documenting the ADK /state pattern (and that it is integration-local) would already help newcomers — see also #1160 / #971.