Writing agent state - Copilotkit

<Callout type="info"> This example demonstrates writing to shared state in the [CopilotKit Feature Viewer](https://feature-viewer.copilotkit.ai/pydantic-ai/feature/shared_state). </Callout>

What is this?

This guide shows you how to write to your agent's state from your application.

When should I use this?

You can use this when you want to provide the user with feedback about what your agent is doing, specifically when your agent is calling tools. CopilotKit allows you to fully customize how these tools are rendered in the chat.

Implementation

<Steps> <Step> ### Run and connect your agent <RunAndConnect components={props.components} /> </Step> <Step> ### Define the Agent State

Create your Pydantic AI agent with a stateful structure. Here's a complete example that tracks language:

```python title="agent.py"
from textwrap import dedent

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext
from pydantic_ai.ag_ui import StateDeps


class AgentState(BaseModel):
    """State for the agent."""
    language: str = "english"


agent = Agent("openai:gpt-5.4-mini", deps_type=StateDeps[AgentState])


@agent.instructions()
async def language_instructions(ctx: RunContext[StateDeps[AgentState]]) -> str:
    """Instructions for the language tracking agent.

    Args:
        ctx: The run context containing language state information.

    Returns:
        Instructions string for the language tracking agent.
    """
    return dedent(
        f"""
        You are a helpful assistant for tracking the language.

        IMPORTANT:
        - ALWAYS use the lower case for the language
        - ALWAYS response in the current language: {ctx.deps.state.language}
        """
    )


app = agent.to_ag_ui(deps=StateDeps(AgentState()))

if __name__ == "__main__":

// ...

function YourMainContent() { const { agent } = useAgent({ agentId: "my_agent", }); const { copilotkit } = useCopilotKit(); // [!code highlight]

// setup to be called when some event in the app occurs const toggleLanguage = async () => { const newLanguage = agent.state?.language === "english" ? "spanish" : "english"; agent.setState({ language: newLanguage });

// add a hint message and re-run the agent
// [!code highlight:7]
agent.addMessage({
  id: crypto.randomUUID(),
  role: "user",
  content: `the language has been updated to ${newLanguage}`,
});
await copilotkit.runAgent({ agent });

};

return ( // ... ); }


### Intermediately Stream and Render Agent State

By default, the Pydantic AI Agent state will only update _between_ Pydantic AI Agent node transitions --
which means state updates will be discontinuous and delayed.

{/* You likely want to render the agent state as it updates **continuously.**

See **[emit intermediate state](/pydantic-ai/shared-state/predictive-state-updates).**  */}