Predictive state updates

This video shows the result of npx copilotkit@latest init with the implementation section applied to it!

What is this?#

A CrewAI Flow'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 CrewAI flow 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#

Install the CopilotKit SDK#

Any LangGraph agent can be used with CopilotKit. However, creating deep agentic experiences with CopilotKit requires our LangGraph SDK.

uv add copilotkit

poetry add copilotkit

pip install copilotkit --extra-index-url https://copilotkit.gateway.scarf.sh/simple/

conda install copilotkit -c copilotkit-channel

npm npm install @copilotkit/sdk-js

Define the state#

We'll be defining a observed_steps field in the state, which will be updated as the agent writes different sections of the report.

agent.py

from copilotkit.crewai import CopilotKitState
from typing import Literal

class AgentState(CopilotKitState):
    observed_steps: list[str]  # Array of completed steps

Emit the intermediate state#

How would you like to emit state updates?

You can either manually emit state updates or configure specific tool calls to emit updates.

↑

Manual Predictive State Updates

Manually emit state updates for maximum control over when updates occur.

🔧

Tool-Based Predictive State Updates

Configure specific tool calls to automatically emit intermediate state updates.

For long-running tasks, you can emit state updates progressively as predictions of the final state. In this example, we simulate a long-running task by executing a series of steps with a one second delay between each update.

agent.py

from copilotkit.crewai import copilotkit_emit_state 
from crewai.flow.flow import Flow, start

class SampleAgentFlow(Flow):
    # ...
    @start()
    async def start_flow(self):
        # ...

        # Simulate executing steps one by one
        steps = [
            "Analyzing input data...",
            "Identifying key patterns...",
            "Generating recommendations...",
            "Formatting final output..."
        ]

        for step in steps:
            self.state["observed_steps"] = self.state.get("observed_steps", []) + [step]
            await copilotkit_emit_state(self.state) 
            await asyncio.sleep(1)

    # ...

Observe the predictions#

These predictions will be emitted as the agent runs, allowing you to track its progress before the final state is determined.

ui/app/page.tsx


// ...

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

    // Add a state renderer to observe predictions
    useAgent({
        agentId: "sample_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>
    )
}

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.