useAgentContext - Copilotkit

useAgentContext is a React hook that provides contextual information to AI agents during their execution. It allows you to dynamically add relevant data that agents can use to make more informed decisions and provide better responses.

What is useAgentContext?

The useAgentContext hook:

Provides contextual information to agents
Automatically manages context lifecycle (add on mount, remove on unmount)
Updates context when values change
Helps agents understand application state and user data

Basic Usage

tsx

import { useAgentContext } from "@copilotkit/react-core";

function UserPreferences() {
  const userSettings = {
    theme: "dark",
    language: "en",
    timezone: "UTC-5",
  };

  useAgentContext({
    description: "User preferences and settings",
    value: userSettings,
  });

  return <div>User preferences loaded</div>;
}

Parameters

The hook accepts a single Context object with the following properties:

description

string (required)

A clear description of what this context represents. This helps agents understand how to use the provided information.

tsx

useAgentContext({
  description: "Current shopping cart contents",
  value: cartItems,
});

value

any (required)

The actual data to provide as context. Can be any serializable value including objects, arrays, strings, or numbers. Anything that is not already a string is stringified with JSON.stringify before it is sent, so the agent receives a JSON string rather than the value you passed — see What the agent receives.

tsx

useAgentContext({
  description: "Current form validation state",
  value: {
    hasErrors: false,
    touchedFields: ["email", "name"],
    dirtyFields: ["email"],
    isSubmitting: false,
  },
});

Examples

User Preferences Context

tsx

import { useAgentContext } from "@copilotkit/react-core";
import { useUserPreferences } from "./hooks/useUserPreferences";

function UserPreferencesContext() {
  const { preferences, isLoading } = useUserPreferences();

  useAgentContext({
    description: "User display preferences and settings",
    value: {
      theme: preferences?.theme || "light",
      language: preferences?.language || "en",
      timezone: preferences?.timezone || "UTC",
      displayDensity: preferences?.displayDensity || "comfortable",
      isLoading,
    },
  });

  return null; // Context-only component
}

Form State Context

tsx

import { useAgentContext } from "@copilotkit/react-core";
import { useState } from "react";

function ContactForm() {
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    subject: "",
    message: "",
  });

  // Provide form state to agent for assistance
  useAgentContext({
    description: "Contact form current state",
    value: {
      formData,
      hasUnsavedChanges: Object.values(formData).some((v) => v !== ""),
      isValid: formData.email.includes("@") && formData.name.length > 0,
    },
  });

  return (
    <form>
      <input
        value={formData.name}
        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
        placeholder="Name"
      />
    </form>
  );
}

Application State Context

tsx

import { useAgentContext } from "@copilotkit/react-core";
import { useLocation } from "react-router-dom";

function AppStateContext() {
  const location = useLocation();
  const currentTime = new Date().toISOString();

  useAgentContext({
    description: "Current application state and navigation",
    value: {
      currentPath: location.pathname,
      queryParams: Object.fromEntries(new URLSearchParams(location.search)),
      timestamp: currentTime,
    },
  });

  return null;
}

Dynamic Data Context

tsx

import { useAgentContext } from "@copilotkit/react-core";
import { useEffect, useState } from "react";

function DynamicDataContext() {
  const [data, setData] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch("/api/context-data");
      setData(await response.json());
    };
    fetchData();
  }, []);

  // Context updates automatically when data changes
  useAgentContext({
    description: "Dynamic application data",
    value: data || { loading: true },
  });

  return null;
}

Multiple Contexts

tsx

import { useAgentContext } from "@copilotkit/react-core";

function MultipleContexts() {
  const userContext = { id: "123", name: "John" };
  const appContext = { version: "1.0.0", features: ["chat", "search"] };

  // Use multiple hooks for different contexts
  useAgentContext({
    description: "User information",
    value: userContext,
  });

  useAgentContext({
    description: "Application configuration",
    value: appContext,
  });

  return <div>Multiple contexts provided</div>;
}

Context Lifecycle

Automatic Management

Context is automatically managed throughout the component lifecycle:

tsx

function ManagedContext() {
  const [count, setCount] = useState(0);

  useAgentContext({
    description: "Counter state",
    value: { count, lastUpdated: Date.now() },
  });

  // Context is:
  // 1. Added when component mounts
  // 2. Updated when count changes
  // 3. Removed when component unmounts

  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

Updates on Change

Context automatically updates when values change:

tsx

function ReactiveContext() {
  const [filters, setFilters] = useState({
    category: "all",
    priceRange: [0, 100],
  });

  // Context updates whenever filters change
  useAgentContext({
    description: "Active search filters",
    value: filters,
  });

  return (
    <div>
      <select
        value={filters.category}
        onChange={(e) => setFilters({ ...filters, category: e.target.value })}
      >
        <option value="all">All</option>
        <option value="electronics">Electronics</option>
        <option value="clothing">Clothing</option>
      </select>
    </div>
  );
}

Best Practices

Descriptive Context Names

Provide clear, descriptive names for your context:

tsx

// ✅ Good - Clear and specific
useAgentContext({
  description: "E-commerce shopping cart with items and totals",
  value: cartData,
});

// ❌ Avoid - Too vague
useAgentContext({
  description: "Data",
  value: cartData,
});

Structured Data

Organize context data in a structured format:

tsx

// ✅ Good - Well-structured data
useAgentContext({
  description: "Order processing state",
  value: {
    orderId: "ORD-123",
    status: "processing",
    items: [{ id: "1", name: "Product", quantity: 2, price: 29.99 }],
    customer: {
      id: "CUST-456",
      email: "[email protected]",
    },
    timestamps: {
      created: "2024-01-01T10:00:00Z",
      updated: "2024-01-01T10:30:00Z",
    },
  },
});

// ❌ Avoid - Unstructured data
useAgentContext({
  description: "Order info",
  value: "Order ORD-123 for [email protected] with 2 items",
});

Performance Optimization

Memoize complex computed values:

tsx

import { useMemo } from "react";

function OptimizedContext({ items }) {
  const contextValue = useMemo(
    () => ({
      itemCount: items.length,
      totalValue: items.reduce((sum, item) => sum + item.price, 0),
      categories: [...new Set(items.map((item) => item.category))],
    }),
    [items],
  );

  useAgentContext({
    description: "Computed inventory statistics",
    value: contextValue,
  });

  return null;
}

What the agent receives

Every registered entry reaches the agent as { description, value }, and value is a JSON string — not the object or array you passed. The AG-UI protocol types it as a string, so this is not an implementation detail you can ignore when writing the agent.

Registering this:

tsx

useAgentContext({
  description: "Incident dashboard records",
  value: [{ id: "INC-1041", severity: "sev1" }],
});

delivers this to the agent:

json

{
  "description": "Incident dashboard records",
  "value": "[{\"id\":\"INC-1041\",\"severity\":\"sev1\"}]"
}

Parse it before reading any field. In a Python agent:

python

import json

def dashboard_records(context):
    entry = next(
        (item for item in context if item["description"] == "Incident dashboard records"),
        None,
    )
    return None if entry is None else json.loads(entry["value"])

In a TypeScript agent:

const entry = context.find(
  (item) => item.description === "Incident dashboard records",
);
const records = entry ? JSON.parse(entry.value) : undefined;

Where that context list surfaces in your agent depends on your framework's AG-UI adapter — see your integration's guide for the field it populates.

<Warning> Do not type-check `value` against the shape you registered. `isinstance(entry["value"], list)` in Python, or `Array.isArray(entry.value)` in TypeScript, can never be true, because `value` is always a string on the wire. An agent that reads such a failed check as "no context was sent" will refuse every request while the browser is registering context correctly, and the two cases are indistinguishable from the UI. </Warning>

Integration with Agents

Context provided through this hook is available to agents during execution:

tsx

import {
  useAgentContext,
  useAgent,
  useCopilotKit,
} from "@copilotkit/react-core";

function IntegratedExample() {
  const { agent } = useAgent();
  const { copilotkit } = useCopilotKit();
  const [productSearch, setProductSearch] = useState("");

  // Provide search context
  useAgentContext({
    description: "Current product search parameters",
    value: {
      searchQuery: productSearch,
      resultsPerPage: 20,
      sortBy: "relevance",
    },
  });

  const handleSearch = async () => {
    // Agent has access to the context when running
    agent.addMessage({
      id: crypto.randomUUID(),
      role: "user",
      content: `Help me refine my search for: ${productSearch}`,
    });

    await copilotkit.runAgent({ agent });
  };

  return (
    <div>
      <input
        value={productSearch}
        onChange={(e) => setProductSearch(e.target.value)}
        placeholder="Search products..."
      />
      <button onClick={handleSearch}>Get AI Help</button>
    </div>
  );
}