Agent App Context

Share app specific context with your agent.

Your agent can answer only about data it can see. Register page data, such as the current user or the current page, with useAgentContext. Then add that data to the agent's messages in your AG-UI server, as shown below.

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.

You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the quickstart guide.

If you do not have an agent yet, the quickstart shows how to create one.

Add the data to the Copilot

The useAgentContext hook adds data as context to the Copilot.

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

    // Define Copilot readable state
    useAgentContext({
        description: "The current user's colleagues",
        value: colleagues,
    });
    return (
        // Your custom UI component
        <>...</>
    );
}

Consume the data in your AG-UI server

The context you register on the frontend is forwarded in the AG-UI RunAgentInput. Use middleware to read it and inject it into the agent's conversation.

main.py (excerpt)

import json
from collections.abc import AsyncGenerator
from typing import Any
from uuid import uuid4

from ag_ui.core import BaseEvent
from agent_framework import Agent, BaseChatClient
from agent_framework_ag_ui import AgentFrameworkAgent


def build_context_system_message(context: Any) -> str | None:
    if not isinstance(context, list) or not context:
        return None

    lines = ["## Context from the application"]
    for entry in context:
        if not isinstance(entry, dict):
            continue

        description = entry.get("description")
        value = entry.get("value")
        if not isinstance(description, str) or not description or value is None:
            continue

        if not isinstance(value, str):
            try:
                value = json.dumps(value, ensure_ascii=False, indent=2)
            except (TypeError, ValueError):
                value = str(value)
        lines.extend(["", description, value])

    return "\n".join(lines) if len(lines) > 1 else None


class ContextAwareAgent(AgentFrameworkAgent):
    """Add app context to this request without mutating the shared agent."""

    async def run(
        self,
        input_data: dict[str, Any],
    ) -> AsyncGenerator[BaseEvent, None]:
        context_prompt = build_context_system_message(input_data.get("context"))
        messages = input_data.get("messages")

        # The adapter skips the model when messages are empty. Context
        # alone must not create an unsolicited model call.
        if context_prompt and isinstance(messages, list) and messages:
            run_id = input_data.get("runId") or str(uuid4())
            request_input = dict(input_data)
            request_input["runId"] = run_id
            request_input["messages"] = [
                {
                    "id": f"{run_id}-app-context",
                    "role": "system",
                    "content": context_prompt,
                },
                *[
                    message
                    for message in messages
                    if not (
                        isinstance(message, dict)
                        and isinstance(message.get("id"), str)
                        and message["id"].endswith("-app-context")
                    )
                ],
            ]
            input_data = request_input

        async for event in super().run(input_data):
            yield event


def create_agent(chat_client: BaseChatClient) -> AgentFrameworkAgent:
    base_agent = Agent(
        name="sample_agent",
        instructions="You are a helpful assistant.",
        client=chat_client,
    )

    return ContextAwareAgent(
        agent=base_agent,
        name="CopilotKitMicrosoftAgentFrameworkAgent",
        description="Assistant using request-local app context.",
        require_confirmation=False,
    )

Context registered with useAgentContext is forwarded in RunAgentInput.Context as AGUIContext entries. TryGetRunAgentInput reads that RunAgentInput from the chat options.

Configuration & Error Handling: This example uses OPENAI_API_KEY for configuration. Set it with user secrets or an environment variable. For production deployments, add appropriate error handling and consider using the Quickstart or Authentication guides for complete setup patterns.

Give it a try

Ask your agent a question about the context (e.g., "Who are my colleagues?"). The agent will use the forwarded context to answer.

How is this guide?