use-agent-context.mdx

title	useAgentContext
description	useAgentContext Hook API Reference

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

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.

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.

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

Examples

User Preferences Context

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

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"
      />
      {/* Rest of form fields */}
    </form>
  );
}

Application State Context

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

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

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:

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:

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:

// ✅ 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:

// ✅ 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: "user@example.com",
    },
    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 user@example.com with 2 items",
});

Performance Optimization

Memoize complex computed values:

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

Integration with Agents

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

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>
  );
}