Reading 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.ui import StateDeps
from pydantic_ai.ui.ag_ui import AGUIAdapter
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import Response
from starlette.routing import Route


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}
        """
    )


async def run_agent(request: Request) -> Response:
    # Build the deps fresh on every request: `dispatch_request` writes the state
    # the client sent into `deps.state`, so a shared instance leaks state between
    # concurrent requests and users.
    return await AGUIAdapter.dispatch_request(
        request, agent=agent, deps=StateDeps(AgentState())
    )


app = Starlette(routes=[Route("/", run_agent, methods=["POST"])])

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

```tsx title="ui/app/page.tsx"
import { useEffect } from "react";
import { useAgent } from "@copilotkit/react-core/v2"; // [!code highlight]

// Define the agent state type, should match the actual state of your agent
type AgentState = {
  language: "english" | "spanish";
}

function YourMainContent() {
  const { agent, isReady } = useAgent({
    agentId: "my_agent",
  });
  const state = (agent.state ?? {}) as Partial<AgentState>;

  useEffect(() => {
    if (!isReady || state.language !== undefined) return;
    agent.setState({ ...(agent.state ?? {}), language: "english" });
  }, [agent, isReady, state.language]);

  // ...

  return (
    // style excluded for brevity
    <div>
      <h1>Your main content</h1>
      <p>Language: {state.language}</p>
    </div>
  );
}
```

<Callout type="warn" title="Important">
  The `name` parameter must exactly match the agent name you defined in your CopilotRuntime configuration (e.g., `my_agent` from the quickstart).
</Callout>

<Callout type="info">
  The `agent.state` in `useAgent` is reactive and will automatically update when the agent's state changes.
</Callout>

import { useAgent } from "@copilotkit/react-core/v2"; // [!code highlight]

// Define the agent state type, should match the actual state of your agent
type AgentState = {
  language: "english" | "spanish";
};

function YourMainContent() {
  const { agent } = useAgent({
    agentId: "my_agent",
  });
  const state = (agent.state ?? {}) as Partial<AgentState>;

  if (!state.language) return null;
  return <div>Language: {state.language}</div>;
}