Agent Context - Copilotkit

Share your application's state and context with the Built-in Agent using the useAgentContext hook. The agent automatically receives this context — no backend configuration needed.

What is this?

The useAgentContext hook lets you register app-specific data that gets included in the agent's context. This could be the current user, page content, shopping cart items, or any data that helps the agent provide relevant responses.

When should I use this?

You want the agent to know about the current state of your app
You need the agent to reference user-specific data (name, preferences, role)
The agent should be aware of what page or view the user is on
You want to provide domain-specific data without hardcoding it into the system prompt

Implementation

<Steps> <Step> ### Register context in your component

Use useAgentContext to share any data with the agent:

tsx

"use client"; // only necessary for Next.js App Router // [!code highlight]
import { useAgentContext } from "@copilotkit/react-core/v2"; // [!code highlight]
import { useState } from "react";

export function Dashboard() {
  const [user] = useState({
    name: "Jane Smith",
    role: "Engineering Manager",
    team: "Platform",
  });

  const [projects] = useState([
    { id: 1, name: "Auth Redesign", status: "in-progress" },
    { id: 2, name: "API v2", status: "planning" },
  ]);

  // Share user info with the agent
  // [!code highlight:4]
  useAgentContext({
    description: "The currently logged-in user",
    value: user,
  });

  // Share project data with the agent
  // [!code highlight:4]
  useAgentContext({
    description: "The user's active projects",
    value: projects,
  });

  return <div></div>;
}

</Step> <Step> ### That's it — no backend setup needed

Unlike LangGraph where you need to configure agent state to receive context, the Built-in Agent handles this automatically. The context you register is included in the agent's system prompt, so it can reference your app data immediately.

User: "What projects am I working on?"
Agent: "You're working on two projects:
  1. Auth Redesign (in progress)
  2. API v2 (planning)"

</Step> </Steps>

Multiple contexts

You can call useAgentContext multiple times across different components. All registered contexts are combined and sent to the agent:

tsx

useAgentContext({
  description: "Current user profile",
  value: { name: "Jane", role: "Manager" },
});

tsx

useAgentContext({
  description: "The page the user is currently viewing",
  value: { page: "settings", section: "notifications" },
});

The agent sees both contexts and can reference either when responding.

Dynamic context

Context updates automatically when the underlying data changes:

tsx

export function TaskList() {
  const [tasks, setTasks] = useState([]);

  // Context updates whenever tasks change // [!code highlight]
  useAgentContext({
    description: "The user's current task list",
    value: tasks,
  });

  return (
    <div>
    </div>
  );
}