# State Rendering

> Render your agent's state with custom UI components in real-time.

## What is this? [#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? [#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 [#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.

```vue title="src/components/ResearchProgress.vue"
<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>
```

```vue title="src/App.vue"
<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.

<Steps>
  <Step>
    ### Map the tool argument with `predict_state_config`

    `predict_state_config` names the tool and the argument to stream into a
    state key. While the model generates the `write_document` call, the
    adapter sends each partial `document` argument to the UI as a state
    update. Returning `state_update(...)` from the tool commits the final
    value when the call completes:

    ```python title="src/agents/shared_state_streaming.py"
    from typing import Annotated

    from agent_framework import tool
    from agent_framework_ag_ui import state_update
    from pydantic import Field

    # Stream tool-argument deltas straight into `state.document` while
    # `write_document` is still streaming.
    PREDICT_STATE_CONFIG: dict[str, dict[str, str]] = {
        "document": {
            "tool": "write_document",
            "tool_argument": "document",
        }
    }


    @tool(
        name="write_document",
        description=(
            "Write a document for the user. Always call this tool when the "
            "user asks you to write, draft, or revise any text. The "
            "`document` argument is streamed per-token into shared state "
            "under the `document` key so the UI renders the body live."
        ),
    )
    def write_document(
        document: Annotated[
            str,
            Field(description="The full document content as a single string."),
        ],
    ):
        return state_update(
            text="Document written to shared state.",
            state={"document": document},
        )
    ```

  </Step>
  <Step>
    ### Seed the state key before the deltas arrive

    The streamed updates are JSON Patch `replace` operations on
    `/document`. The agent's initial state is `{}`, and a `state_schema`
    defines properties but sets no starting values, so on the first turn the
    path does not exist yet. The
    frontend rejects the patch ("Failed to apply state patch") and the run
    never settles.

    Emit a `STATE_SNAPSHOT` that carries the key right after `RUN_STARTED`,
    keeping any value from an earlier turn:

    ```python title="src/agents/shared_state_streaming.py"
    from collections.abc import AsyncGenerator
    from typing import Any

    from ag_ui.core import BaseEvent, EventType, StateSnapshotEvent
    from agent_framework import Agent, BaseChatClient
    from agent_framework_ag_ui import AgentFrameworkAgent


    class SharedStateStreamingFrameworkAgent(AgentFrameworkAgent):
        async def run(  # type: ignore[override]
            self,
            input_data: dict[str, Any],
        ) -> AsyncGenerator[BaseEvent, None]:
            incoming = input_data.get("state")
            state = incoming if isinstance(incoming, dict) else {}
            document = state.get("document", "")
            seeded = False
            async for event in super().run(input_data):
                yield event
                # RUN_STARTED must be the first event; the seed follows it.
                if not seeded and getattr(event, "type", None) == EventType.RUN_STARTED:
                    yield StateSnapshotEvent(
                        type=EventType.STATE_SNAPSHOT,
                        snapshot={**state, "document": document},
                    )
                    seeded = True


    def create_shared_state_streaming_agent(
        chat_client: BaseChatClient,
    ) -> AgentFrameworkAgent:
        base_agent = Agent(
            client=chat_client,
            name="shared_state_streaming_agent",
            instructions=SYSTEM_PROMPT,  # tells the model to call write_document
            tools=[write_document],
        )

        return SharedStateStreamingFrameworkAgent(
            agent=base_agent,
            name="SharedStateStreamingAgent",
            description=(
                "Per-token state streaming: `write_document` arg deltas land "
                "in `state.document` as the tool call is generated."
            ),
            predict_state_config=PREDICT_STATE_CONFIG,
            require_confirmation=False,
        )
    ```

  </Step>
</Steps>

```python title="src/agents/shared_state_streaming.py"
# Tells the runtime to stream tool-argument deltas straight into
# `state.document` while `write_document` is still streaming — matches
# LGP's StateStreamingMiddleware setup.
PREDICT_STATE_CONFIG: dict[str, dict[str, str]] = {
    "document": {
        "tool": "write_document",
        "tool_argument": "document",
    }
}
```

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.

<IntegrationGrid
  path="generative-ui/state-rendering"
  exclude={["agno", "agent-spec"]}
/>
