State Rendering
Render your agent's state with custom UI components in real-time.
What is this?
State rendering lets you build UI that reflects your agent's state in real-time. As your agent progresses through nodes and emits state updates, your frontend renders those changes, showing progress, drafts, or intermediate results.
When should I use this?
Use state rendering when you want to:
- Show real-time progress (e.g. "Researching... 2/5 complete")
- Display drafts that update as the agent works
- Build dashboards that reflect agent state
- Render structured output outside of the chat
How it works in code
On the frontend, subscribe to the agent's state. Each time the backend forwards a fresh value, your component re-renders with the latest partial output. useAgent returns an agent ref; read agent.value?.state in script or let templates unwrap the ref. Keep the provider in an ancestor SFC.
<script setup lang="ts">
import { computed } from "vue";
import { useAgent, UseAgentUpdate } from "@copilotkit/vue/v2";
type ResearchState = { status?: string; draft?: string; completed?: number; total?: number };
const { agent } = useAgent({
agentId: "researcher",
updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged],
});
const state = computed(() => (agent.value?.state ?? {}) as ResearchState);
</script>
<template>
<section aria-live="polite">
<p>{{ state.status ?? "Idle" }}</p>
<progress :value="state.completed ?? 0" :max="state.total ?? 1" />
<article v-if="state.draft">{{ state.draft }}</article>
</section>
</template><script setup lang="ts">
import { CopilotChat, CopilotKitProvider } from "@copilotkit/vue/v2";
import ResearchProgress from "./components/ResearchProgress.vue";
</script>
<template>
<CopilotKitProvider runtime-url="/api/copilotkit">
<ResearchProgress />
<CopilotChat agent-id="researcher" />
</CopilotKitProvider>
</template>On the backend, a state-streaming mapping forwards a tool argument into a state key while the model writes it. Some frameworks provide that as middleware. Direct SDK adapters can emit STATE_SNAPSHOT events from their streaming loop. Either way, the UI can watch the answer assemble token-by-token rather than appearing in one burst between checkpoints.
Install the ADK + AG-UI bridge
pip install ag-ui-adkDeclare the predicted state mapping
ADK state streaming uses PredictStateMapping to map the streaming
write_document tool argument into state["document"]. Add
AGUIToolset() to the agent so CopilotKit can forward the state deltas to
the UI.
from __future__ import annotations
from ag_ui_adk import AGUIToolset
from ag_ui_adk.config import PredictStateMapping
from google.adk.agents import LlmAgent
from google.adk.tools import ToolContext
from agents.shared_chat import get_model, stop_on_terminal_text
def write_document(tool_context: ToolContext, document: str) -> dict:
"""Write a document into shared state.
Whenever the user asks you to write or draft anything (essay, poem,
email, summary, etc.), call this tool with the full content as a
single string. The UI renders state["document"] live as you type.
Argument name `document` mirrors langgraph-python's `write_document`
signature so the shared D5 fixture (`tool_argument="document"`) and
the LGP-aligned PredictStateMapping below stay in lock-step.
"""
tool_context.state["document"] = document
return {"status": "ok", "length": len(document)}
_INSTRUCTION = (
"You are a collaborative writing assistant. Whenever the user asks "
"you to write, draft, or revise any piece of text, ALWAYS call the "
"`write_document` tool with the full content as a single string. "
"Never paste the document into a chat message directly — the document "
"belongs in shared state and the UI renders it live as you type."
)
shared_state_streaming_agent = LlmAgent(
name="SharedStateStreamingAgent",
model=get_model(),
instruction=_INSTRUCTION,
tools=[write_document, AGUIToolset()],
after_model_callback=stop_on_terminal_text,
)
SHARED_STATE_STREAMING_PREDICT_STATE = [
PredictStateMapping(
state_key="document",
tool="write_document",
tool_argument="document",
emit_confirm_tool=False,
stream_tool_call=True,
),
]Pass the mapping to ADKAgent
The mapping does nothing until it reaches the ADKAgent middleware. Pass
it as predict_state, and turn on streaming_function_call_arguments so
the middleware receives the tool arguments while the model writes them.
The showcase server builds each endpoint this way:
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
middleware = ADKAgent(
adk_agent=shared_state_streaming_agent,
user_id="demo_user",
session_timeout_seconds=3600,
use_in_memory_services=True,
predict_state=SHARED_STATE_STREAMING_PREDICT_STATE,
streaming_function_call_arguments=True,
)
add_adk_fastapi_endpoint(app, middleware, path="/shared-state-streaming")With predict_state, the frontend gets document while the model writes
the document argument of write_document. When the tool runs,
tool_context.state stores the final value.
Per-token streaming needs google-adk 1.24.0 or later through Vertex AI.
On older versions, or through Gemini in Google AI Studio, the middleware
logs a UserWarning at startup and streams in larger chunks. The state
still updates, only less often.
Stop after the final model response
The agent above imports stop_on_terminal_text and registers it as its
after_model_callback. This prevents Gemini from issuing the same tool
call again after its final text response. See the canonical
stop_on_terminal_text implementation
when adapting the callback for your project.
from __future__ import annotations
from ag_ui_adk import AGUIToolset
from ag_ui_adk.config import PredictStateMapping
from google.adk.agents import LlmAgent
from google.adk.tools import ToolContext
from agents.shared_chat import get_model, stop_on_terminal_text
def write_document(tool_context: ToolContext, document: str) -> dict:
"""Write a document into shared state.
Whenever the user asks you to write or draft anything (essay, poem,
email, summary, etc.), call this tool with the full content as a
single string. The UI renders state["document"] live as you type.
Argument name `document` mirrors langgraph-python's `write_document`
signature so the shared D5 fixture (`tool_argument="document"`) and
the LGP-aligned PredictStateMapping below stay in lock-step.
"""
tool_context.state["document"] = document
return {"status": "ok", "length": len(document)}
_INSTRUCTION = (
"You are a collaborative writing assistant. Whenever the user asks "
"you to write, draft, or revise any piece of text, ALWAYS call the "
"`write_document` tool with the full content as a single string. "
"Never paste the document into a chat message directly — the document "
"belongs in shared state and the UI renders it live as you type."
)
shared_state_streaming_agent = LlmAgent(
name="SharedStateStreamingAgent",
model=get_model(),
instruction=_INSTRUCTION,
tools=[write_document, AGUIToolset()],
after_model_callback=stop_on_terminal_text,
)
SHARED_STATE_STREAMING_PREDICT_STATE = [
PredictStateMapping(
state_key="document",
tool="write_document",
tool_argument="document",
emit_confirm_tool=False,
stream_tool_call=True,
),
]
Ask the researcher agent to write a report. The status line and the progress bar change while the agent runs, and the draft text grows as the tokens arrive.
Treat agent state as untrusted external data. Validate it before using it for privileged actions, and avoid putting secrets in state that is streamed to the browser.
How is this guide?