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.

Program.cs
#pragma warning disable OPENAI001
using System.Runtime.CompilerServices;
using System.Text;
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.AI;
using OpenAI;
using OpenAI.Chat;
using AIChatMessage = Microsoft.Extensions.AI.ChatMessage;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();
var app = builder.Build();

string openAiApiKey = builder.Configuration["OPENAI_API_KEY"]
    ?? throw new InvalidOperationException("Set OPENAI_API_KEY");

// Create the base agent
AIAgent baseAgent = new OpenAIClient(openAiApiKey)
    .GetChatClient("gpt-6-luna")
.AsIChatClient().AsBuilder()
.ConfigureOptions(options => options.RawRepresentationFactory = _ =>
new OpenAI.Chat.ChatCompletionOptions { ReasoningEffortLevel = new("none") })
.Build()
    .AsAIAgent(
        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.MapAGUIServer("/", agent);
await app.RunAsync();

// Middleware to inject useAgentContext context as a system message
async IAsyncEnumerable<AgentResponseUpdate> InjectContextMiddleware(
    IEnumerable<AIChatMessage> messages,
    AgentSession? session,
    AgentRunOptions? options,
    AIAgent innerAgent,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    // Recover the AG-UI request and inject its context if present
    if (options is ChatClientAgentRunOptions { ChatOptions: { } chatOptions } &&
        chatOptions.TryGetRunAgentInput(out RunAgentInput? input) &&
        input?.Context is { Count: > 0 } context)
    {
        var contextBuilder = new StringBuilder();
        contextBuilder.AppendLine("The following context from the user's application is available:");
        foreach (AGUIContext item in context)
        {
            contextBuilder.AppendLine($"- {item.Description}: {item.Value}");
        }

        var contextMessage = new AIChatMessage(
            ChatRole.System,
            [new TextContent(contextBuilder.ToString())]);

        messages = messages.Append(contextMessage);
    }

    await foreach (var update in innerAgent.RunStreamingAsync(messages, session, options, cancellationToken))
    {
        yield return update;
    }
}

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?