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

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

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({ modelKwargs: { reasoning_effort: "none" }, model: "gpt-6-luna" }).invoke(
    [systemMessage, ...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?