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.
"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.
# ...
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 propertiesConsume the data in your LangGraph agent
CopilotKit writes the context entries to copilotkit.context in your agent state. Read them from there.
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?