Agent App Context

Share app specific context with your agent.

Your agent can answer only about data it can see. The signed-in user and the rows on screen live in your React app. Register them with useAgentContext, and CopilotKit sends them to your LangGraph agent on every run.

Implementation

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 adds 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 that your agent state includes the CopilotKit state: inherit from CopilotKitState in Python, or spread CopilotKitStateSchema.fields in TypeScript.

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

Consume the data in your LangGraph agent

CopilotKit writes the context entries to copilotkit.context in your agent state. Read them from there.

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-6-luna", reasoning_effort="none").invoke(
        [system_message, *state["messages"]],
        config
    )

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

Give it a try

Ask "Who are my colleagues?". The agent names John Doe, Jane Smith, and Bob Wilson with their roles.

How is this guide?