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.
"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.
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?