# 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 [#implementation]

<Callout type="warn" title="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.
</Callout>

<Steps>
    <Step>
      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](/react-native/ms-agent-python/quickstart) guide.

      If you do not have an agent yet, the quickstart shows how to create one.
    </Step>
    <Step>
        ### Add the data to the Copilot [#add-the-data-to-the-copilot]

        The [`useAgentContext` hook](/reference/v2/hooks/useAgentContext) adds data as context to the Copilot.

        ```tsx title="YourComponent.tsx" showLineNumbers {1, 7-10}
        "use client" // only necessary if you are using Next.js with the App Router. // [!code highlight]
        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
            // [!code highlight:4]
            useAgentContext({
                description: "The current user's colleagues",
                value: colleagues,
            });
            return (
                // Your custom UI component
                <>...</>
            );
        }
        ```
    </Step>

    <Step>
        ### Consume the data in your AG-UI server [#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.

        <Tabs groupId="language_microsoft-agent-framework_agent" items={['.NET', 'Python']} persist>
          <Tab value=".NET">
            ```csharp title="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;
                }
            }
            ```
          </Tab>
          <Tab value="Python">
            ```python title="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,
                )
            ```
          </Tab>
        </Tabs>

        <Callout type="info">
          Context registered with `useAgentContext` is forwarded in `RunAgentInput.Context` as `AGUIContext` entries. `TryGetRunAgentInput` reads that `RunAgentInput` from the chat options.
        </Callout>

        <Callout type="tip">
          **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](/react-native/ms-agent-python/quickstart) or [Authentication](/auth) guides for complete setup patterns.
        </Callout>
    </Step>
    <Step>
        ### Give it a try [#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.
    </Step>

</Steps>
