CopilotKit + AG-UI + Microsoft Foundry hosted agents

Use this skill when a React/Next.js app uses CopilotKit and talks over AG-UI to a Microsoft Agent Framework (MAF) agent hosted in Microsoft Foundry. This covers new builds and changes to existing apps. Foundry hosted agents are a paid Azure service.

Scaffold the agent with azd ai agent init and the frontend with your usual React/Next.js tooling. Then follow this skill for everything that connects them.

Mental model

React (CopilotKit v2)        CopilotKitProvider / CopilotChat threadId=<conv_ id> / useInterrupt
      │ HTTP
CopilotKit runtime           CopilotRuntime({ agents: { default: new HttpAgent({ url }) } })
      │ AG-UI (SSE)
AG-UI gateway (FastAPI)      add_agent_framework_fastapi_endpoint(app, AgentFrameworkAgent(FoundryAgent(...),
                               use_service_session=True, service_session_id_from_thread_id=True))   ← keeps no thread state
      │ OpenAI Responses + Entra token (https://ai.azure.com/.default)
Foundry hosted agent         ResponsesHostServer(Agent(tools=[...]))  ← deployed with azd

A deployed hosted agent does not speak AG-UI. It exposes .../agents/<name>/endpoint/protocols/openai/responses (Responses protocol) or .../protocols/invocations. Translate with MAF's own adapter (FoundryAgent + agent-framework-ag-ui) instead of writing an SSE translator by hand. Browsers cannot hold the Entra token, so the gateway is always server-side.

Use the platform first

Before you write any plumbing, check this table. Each row is something older codebases built by hand.

Choose the wiring

Code for each is in references/wiring.md. In an existing codebase, identify the wiring before you change anything:

• FoundryAgent(...) wrapped by add_agent_framework_fastapi_endpoint means A.
• Agent(client=...) wrapped directly means B.
• A custom AbstractAgent calling /responses with background means C.
• protocol: invocations in azure.yaml means D.

Workflow

1. Pick or identify the wiring (table above).
2. Use the latest release of every package (@copilotkit/*, @ag-ui/*, agent-framework-*, azd and its azure.ai.agents extension). Then ground on live sources:

• the Microsoft Learn MCP server for MAF and Foundry
• the Foundry MCP server for project state
• docs.copilotkit.ai and the .d.ts files bundled in the installed @copilotkit/* packages
• docs.ag-ui.com

APIs move between minor versions, so don't trust memorized names.

1. Build or change it with a playbook below.
2. Verify adversarially against the completion criteria. A compiling build, a started server, or one good chat reply is not proof.

Playbooks

Build a new app end to end (wiring A)

1. In a fresh directory, run azd ai agent init --no-prompt ... against the project. Confirm azd env get-values shows FOUNDRY_PROJECT_ENDPOINT, then write tools in main.py (wiring §1).
2. Run it locally with azd ai agent run (port 8088) and smoke-test it with azd ai agent invoke --local "hi".
3. azd deploy (each deploy creates a new agent version), then azd ai agent invoke "hi".
4. Add the AG-UI gateway exactly as in wiring §2, including the thread-ID-is-conversation-ID flags and the interop shim. Create a conversation, then test chat and an approve resume with curl -N using its conv_… ID as threadId before touching the UI.
5. Add the conversation route, the CopilotKit runtime route and the React provider (wiring §3).
6. Add useInterrupt approval UI and a tool renderer (hitl.md).
7. Verify every completion criterion, first locally and then against the deployed agent.

Add or change an agent tool

1. Define it with @tool (Python) or AIFunctionFactory.Create (.NET), using typed and described parameters.
2. Keep parameter descriptions free of concrete example values for data the model must derive. Models copy literal examples.
3. Return compact values. Rich formatting belongs in the UI renderer.
4. Side-effecting tools get approval_mode="always_require" (hitl.md).
5. Redeploy the hosted agent. Tools live in the hosted agent, not the gateway.
6. Verify through the UI that TOOL_CALL_* events stream, and that any component parsing the arguments still works.

Generative UI and shared state (CopilotKit v2 hooks)

State patterns emit STATE_SNAPSHOT/STATE_DELTA only when the adapter can see the agent's state:

• Wiring B gets them natively.
• Wiring A needs them declared on the gateway's AgentFrameworkAgent. Test this before you promise the feature.
• Wiring C has no state events unless you synthesize them.

Debug a broken flow

Work from the lowest layer upward:

1. Call the hosted agent with azd ai agent invoke or curl against /responses.
2. Call the gateway with a real conversation ID. A made-up thread ID returns HTTP 500 with this wiring:

```bash
CONV=$(curl -s -X POST "$FOUNDRYPROJECTENDPOINT/agents/$FOUNDRYAGENTNAME/endpoint/protocols/openai/conversations?api-version=v1" \
-H "Authorization: Bearer $(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)" \
-H 'content-type: application/json' -d '{}' | jq -r .id)
curl -N -X POST / -H 'content-type: application/json' -d '{"threadId":"'$CONV'","runId":"r1","messages":[{"id":"m1","role":"user","content":"hi"}],"tools":[],"context":[],"state":{},"forwardedProps":{}}'
```

1. Test the CopilotKit route.
2. Test the browser.

The first layer that fails owns the bug. Then match the symptom in troubleshooting.md. Use azd ai agent monitor for hosted-agent logs.

Upgrade dependencies

Follow the version rules in troubleshooting.md. Upgrade all packages together, then re-run the completion criteria live.

Completion criteria

A change is done only when all of these hold:

1. The chat path works through the real UI, not only through curl.
2. Every approval-gated tool was tested both ways:

• Approve: the tool runs once on the server and the side effect is observable.
• Reject: the tool does not run, and the agent acknowledges it.

1. After an approval, a follow-up turn in the same thread does not re-run the gated tool.
2. Tool and approval cards still render after RUN_FINISHED, not only while streaming.
3. For deployed changes, checks 1–4 passed against the deployed agent and gateway. A successful deployment proves nothing about behavior.