Readables

One of the most common use cases for CopilotKit is to register app state and context using useAgentContext. This way, you can notify CopilotKit of what is going on in your app in real time. Some examples might be: the current user, the current page, etc.

This context can then be shared with your LangGraph agent.

Implementation#

Check out the Frontend Data documentation to understand what this is and how to use it.

Context values arrive as JSON strings

The AG-UI protocol defines a context value as a string. Therefore useAgentContext calls JSON.stringify on any value that is not already a string, and your agent receives the JSON text instead of the object or the array.

Parse the value before you read a field from it. Use json.loads(item["value"]) in Python, or JSON.parse(item.value) in TypeScript. If you skip the parse step, an index such as colleagues[0] returns a single character, and a shape check such as isinstance(value, list) can never pass.

Do not stringify the value again, because that produces double encoding. A value that is already a string is sent unchanged, so no parse step is needed for it.

Add the data to the Copilot#

The useAgentContext hook is used to add data as context to the agent.

YourComponent.tsx

"use client" // only necessary if you are using Next.js with the App Router.
import { useAgentContext } from "@copilotkit/react-core/v2"; 
import { useState } from 'react';

export function YourComponent() {
  // Create colleagues state with some sample data
  const [colleagues, setColleagues] = useState([
    { id: 1, name: "John Doe", role: "Developer" },
    { id: 2, name: "Jane Smith", role: "Designer" },
    { id: 3, name: "Bob Wilson", role: "Product Manager" }
  ]);

  // Share context with the agent
  useAgentContext({
    description: "The current user's colleagues",
    value: colleagues,
  });
  return (
    // Your custom UI component
    <>...</>
  );
}

Set up your agent state#

Make sure your agent state inherits from CopilotKit state definition

agent.py

# ...
from copilotkit import CopilotKitState # extends MessagesState
# ...

# This is the state of the agent.
# It inherits from the CopilotKitState properties from CopilotKit.
class AgentState(CopilotKitState):
    # ... Your defined state properties

agent-js/src/agent.ts

// ...
import { StateSchema } from "@langchain/langgraph";
import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";
// ...

// This is the state of the agent.
// It inherits from the CopilotKitState properties from CopilotKit.
export const AgentStateSchema = new StateSchema({
  // ... Your defined state properties
  ...CopilotKitStateSchema.fields,
});
export type AgentState = typeof AgentStateSchema.State;

Consume the data in your LangGraph agent#

The state of a LangGraph agent is the "hub" for applicative information used by the agent. Naturally, the context from CopilotKit will be injected there.

In both Python and TypeScript, the CopilotKit state key is lowercase copilotkit. Read state.copilotkit.context in TypeScript; the SDK's state schema does not define a copilotKit field.

agent.py

import json 

from langchain_core.runnables import RunnableConfig
from langchain_core.messages import SystemMessage
from langchain_openai import ChatOpenAI
from copilotkit import CopilotKitState

# add the agent state definition from the previous step
class AgentState(CopilotKitState):
    # ... Your defined state properties

def chat_node(state: AgentState, config: RunnableConfig):
    # Extract the colleagues from CopilotKit context
    colleagues_context_item = next(
        (item for item in state["copilotkit"]["context"] if item.get("description") == "The current user's colleagues"),
        None
    )

    # The value is a JSON string, so parse it to read the fields
    colleagues = []
    if colleagues_context_item:
        colleagues = json.loads(colleagues_context_item["value"])

    # Now each entry is a dict, so colleague["name"] works
    colleague_list = ", ".join(f"{c['name']} ({c['role']})" for c in colleagues)

    # Provide the list of colleagues to the LLM
    system_message = SystemMessage(
        content=f"""You are a helpful assistant that can help emailing colleagues.
        The user's colleagues are: {colleague_list}"""
    )

    response = ChatOpenAI(model="gpt-5.4").invoke(
        [system_message, *state["messages"]],
        config
    )

    return {
        **state,
        "messages": response,
    }

agent-js/src/agent.ts

import { SystemMessage } from "@langchain/core/messages";
import { ChatOpenAI } from "@langchain/openai";

// add the agent state definition from the previous step
export const AgentStateSchema = new StateSchema({
  // ... Your defined state properties
  ...CopilotKitStateSchema.fields,
});
export type AgentState = typeof AgentStateSchema.State;

async function chat_node(state: AgentState, config: RunnableConfig) {
  // Extract the colleagues from CopilotKit context
  const copilotKitContext = state.copilotkit.context
  const colleaguesContextItem = copilotKitContext.find(contextItem => contextItem.description === "The current user's colleagues")

  // The value is a JSON string, so parse it to read the fields
  const colleagues = colleaguesContextItem ? JSON.parse(colleaguesContextItem.value) : [];

  // Now each entry is an object, so colleague.name works
  const colleagueList = colleagues.map((c) => `${c.name} (${c.role})`).join(", ");

  // Provide the list of colleagues to the LLM
  const systemMessage = new SystemMessage({
    content: `
      You are a helpful assistant that can help emailing colleagues.
      The user's colleagues are: ${colleagueList}
    `,
  });

  const response = await new ChatOpenAI({ model: "gpt-5.4" }).invoke(
    [systemMessage, ...state.messages],
    config
  );

  return {
    ...state,
    messages: response,
  };
}

Give it a try!#

Ask your agent a question about the context. It should be able to answer!