Predictive state updates

This example demonstrates predictive state updates in the CopilotKit Feature Viewer.

What is this?#

A Pydantic AI Agent's state updates discontinuosly; only across function transitions in the flow. But even a single function in the flow often takes many seconds to run and contain sub-steps of interest to the user.

Agent-native applications reflect to the end-user what the agent is doing as continuously possible.

CopilotKit enables this through its concept of predictive state updates.

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 to:

Keep users engaged by avoiding long loading indicators
Build trust by demonstrating what the agent is working on
Enable agent steering - allowing users to course-correct the agent if needed

Important Note#

When a function in your Pydantic AI agent finishes executing, its returned state becomes the single source of truth. While intermediate state updates are great for real-time feedback, any changes you want to persist must be explicitly included in the function's final returned state. Otherwise, they will be overwritten when the function completes.

Implementation#

Define the state#

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

agent.py

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


class AgentState(BaseModel):
    """State for the agent."""
    observed_steps: list[str] = []


agent = Agent('openai:gpt-5.4-mini', deps_type=StateDeps[AgentState])
app = agent.to_ag_ui(deps=StateDeps(AgentState()))


if __name__ == "__main__":

// ...

const YourMainContent = () => {
    // Get access to both predicted and final states
    const { agent } = useAgent({ agentId: "my_agent" });

    // Add a state renderer to observe predictions
    useAgent({
        agentId: "my_agent",
        render: ({ state }) => {
            if (!state.observed_steps?.length) return null;
            return (
                <div>
                    <h3>Current Progress:</h3>
                    <ul>
                        {state.observed_steps.map((step, i) => (
                            <li key={i}>{step}</li>
                        ))}
                    </ul>
                </div>
            );
        },
    });

    return (
        <div>
            <h1>Agent Progress</h1>
            {agent.state?.observed_steps?.length > 0 && (
                <div>
                    <h3>Final Steps:</h3>
                    <ul>
                        {agent.state.observed_steps.map((step, i) => (
                            <li key={i}>{step}</li>
                        ))}
                    </ul>
                </div>
            )}
        </div>
    )
}

Important

The name parameter must exactly match the agent name you defined in your CopilotRuntime configuration (e.g., my_agent from the quickstart).

Give it a try!#

Now you'll notice that the state predictions are emitted as the agent makes progress, giving you insight into its work before the final state is determined. You can apply this pattern to any long-running task in your agent.