Readables
Share app specific context with your agent.
One of the most common use cases for CopilotKit is to register app state and context using useAgentContext.
This way, you can notify CopilotKit of what is going in your app in real time.
Some examples might be: the current user, the current page, etc.
This context can then be shared with your AG-UI server and agent logic.
Implementation#
Check out the Frontend Data documentation to understand what this is and how to use 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 Getting Started guide.
If you don't already have an agent, you can use the coagent starter as a starting point as this guide uses it as a starting point.
Add the data to the Copilot#
The useAgentContext hook is used to add data as context to the Copilot.
"use client" // only necessary if you are using Next.js with the App Router.
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 to your AG-UI server in ChatOptions.AdditionalProperties["ag_ui_context"]. Use middleware to access this context and inject it into the agent's conversation.
using System.Runtime.CompilerServices;
using System.Text;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.AI;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUI();
var app = builder.Build();
string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]!;
string deployment = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]!;
// Create the base agent
AIAgent baseAgent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
.GetChatClient(deployment)
.CreateAIAgent(
name: "AGUIAssistant",
instructions: "You are a helpful assistant. Use the provided context about colleagues to answer questions.");
// Wrap the agent with middleware to inject context
AIAgent agent = baseAgent
.AsBuilder()
.Use(runFunc: null, runStreamingFunc: InjectContextMiddleware)
.Build();
// Map the AG-UI endpoint
app.MapAGUI("/", agent);
await app.RunAsync();
// Middleware to inject useAgentContext context as a system message
async IAsyncEnumerable<AgentRunResponseUpdate> InjectContextMiddleware(
IEnumerable<ChatMessage> messages,
AgentThread? thread,
AgentRunOptions? options,
AIAgent innerAgent,
CancellationToken cancellationToken)
{
// Extract context from AG-UI additional properties and inject if present
if (options is ChatClientAgentRunOptions { ChatOptions.AdditionalProperties: { } properties } &&
properties.TryGetValue("ag_ui_context", out KeyValuePair<string, string>[]? context) &&
context?.Length > 0)
{
var contextBuilder = new StringBuilder();
contextBuilder.AppendLine("The following context from the user's application is available:");
foreach (var item in context)
{
contextBuilder.AppendLine($"- {item.Key}: {item.Value}");
}
var contextMessage = new ChatMessage(
ChatRole.System,
[new TextContent(contextBuilder.ToString())]);
messages = messages.Append(contextMessage);
}
await foreach (var update in innerAgent.RunStreamingAsync(messages, thread, options, cancellationToken))
{
yield return update;
}
}
from agent_framework import Agent, SupportsChatGetResponse
from agent_framework.ag_ui import AgentFrameworkAgent
def create_agent(chat_client: SupportsChatGetResponse) -> AgentFrameworkAgent:
"""
Minimal agent for agent app context demo (frontend context is forwarded automatically).
"""
base_agent = Agent(
name="sample_agent",
instructions="You are a helpful assistant.",
client=chat_client,
)
return AgentFrameworkAgent(
agent=base_agent,
name="CopilotKitMicrosoftAgentFrameworkAgent",
description="Assistant using app context forwarded from the frontend.",
require_confirmation=False,
)Context registered with useAgentContext is automatically forwarded by the AG-UI protocol in ChatOptions.AdditionalProperties["ag_ui_context"] as an array of key-value pairs (description → value). The middleware extracts and injects this context into the conversation.
Configuration & Error Handling: This example uses environment variables for configuration. Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME via appsettings.json, user-secrets, or environment variables. 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!