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.
| Need |
Native primitive (don't hand-roll) |
| Conversation history across turns and restarts |
Foundry conversations: create one per chat, use its conv_… ID as the AG-UI thread ID, and the gateway passes it through (no snapshot store) |
| Durable tool approvals |
ResponsesHostServer persists approval requests by default (FoundryFunctionApprovalStore). The AG-UI adapter turns them into AG-UI interrupts and forwards decisions back to the hosted agent |
| Runs that survive browser disconnects |
Responses background: true + store: true, then poll or reconnect (see wiring) |
| Durable multi-step workflows with gates |
Invocations hosted agent + @multi_turn_task + FoundryStateStore |
| Per-user files for the agent |
Session Files API; the agent reads $HOME with its own tools. Never inline large documents into the prompt |
| Long-term user memory |
Foundry Memory Store (user scope) or FoundryMemoryProvider |
| Tool catalogs, web search, code interpreter |
Foundry Toolbox (FoundryToolbox) with Tool Search, instead of listing every tool up front |
| Live docs while coding |
The Microsoft Learn and Foundry MCP servers (bundled with this skill's plugin) |
Choose the wiring
| If the app needs… |
Use |
Gateway size |
| Hosted agent + chat + tools + approvals (default) |
A. AG-UI gateway over a Responses hosted agent |
~50 lines of Python |
| Every state pattern, local prototype, no Foundry compute |
B. In-process AG-UI (agent runs inside the FastAPI app) |
~15 lines |
| Background runs that keep going after disconnect, reconnect, per-user conversation lists |
C. Background-runs gateway (custom AG-UI agent over Foundry conversations) |
~150 lines of TypeScript |
| Multi-step plan → approve → execute, irreversible steps that must not run twice |
D. Invocations hosted agent alongside A or C |
REST proxy |
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
Pick or identify the wiring (table above).
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.
Build or change it with a playbook below.
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)
- 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).
- Run it locally with
azd ai agent run (port 8088) and smoke-test it with azd ai agent invoke --local "hi".
azd deploy (each deploy creates a new agent version), then azd ai agent invoke "hi".
- 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.
- Add the conversation route, the CopilotKit runtime route and the React provider (wiring §3).
- Add
useInterrupt approval UI and a tool renderer (hitl.md).
- Verify every completion criterion, first locally and then against the deployed agent.
Add or change an agent tool
- Define it with
@tool (Python) or AIFunctionFactory.Create (.NET), using typed and described parameters.
- Keep parameter descriptions free of concrete example values for data the model must derive. Models copy literal examples.
- Return compact values. Rich formatting belongs in the UI renderer.
- Side-effecting tools get
approval_mode="always_require" (hitl.md).
- Redeploy the hosted agent. Tools live in the hosted agent, not the gateway.
- 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)
| Pattern |
Agent side |
Frontend hook |
| Frontend tool (agent calls the UI) |
none; arrives in RunAgentInput.tools |
useFrontendTool |
| Render a backend tool call |
normal @tool |
useRenderTool / useRenderToolCall / useDefaultRenderTool |
| Human approval of a tool call |
approval_mode="always_require" |
useInterrupt → resolve({approved}) |
| Agent asks the user for input (frontend-resolved tool) |
none |
useHumanInTheLoop → respond(...) |
| Shared or predictive state |
state_schema / predict_state_config on AgentFrameworkAgent |
useAgent (read agent.state) |
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:
Call the hosted agent with azd ai agent invoke or curl against /responses.
Call the gateway with a real conversation ID. A made-up thread ID returns HTTP 500 with this wiring:
CONV=$(curl -s -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents/$FOUNDRY_AGENT_NAME/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 <gateway>/ -H 'content-type: application/json' -d '{"threadId":"'$CONV'","runId":"r1","messages":[{"id":"m1","role":"user","content":"hi"}],"tools":[],"context":[],"state":{},"forwardedProps":{}}'
Test the CopilotKit route.
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:
- The chat path works through the real UI, not only through curl.
- 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.
- After an approval, a follow-up turn in the same thread does not re-run the gated tool.
- Tool and approval cards still render after
RUN_FINISHED, not only while streaming.
- For deployed changes, checks 1–4 passed against the deployed agent and gateway. A successful deployment proves nothing about behavior.
1---2name: foundry-hosted-agent-copilotkit3description: 'Build and evolve agentic web apps that pair a CopilotKit React frontend with a Microsoft Agent Framework agent running as a Microsoft Foundry hosted agent, connected over the AG-UI protocol. Covers choosing the wiring, using Foundry-native primitives instead of hand-rolled plumbing, agent tools, human-in-the-loop approvals, generative UI and shared state, local run and azd deploy, debugging the event stream, and safe upgrades.'4metadata:5 source: https://skillmd.com/skills/github/foundry-hosted-agent-copilotkit6---78# CopilotKit + AG-UI + Microsoft Foundry hosted agents910Use 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.1112Scaffold 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.1314## Mental model1516```text17React (CopilotKit v2) CopilotKitProvider / CopilotChat threadId=<conv_ id> / useInterrupt18 │ HTTP19CopilotKit runtime CopilotRuntime({ agents: { default: new HttpAgent({ url }) } })20 │ AG-UI (SSE)21AG-UI gateway (FastAPI) add_agent_framework_fastapi_endpoint(app, AgentFrameworkAgent(FoundryAgent(...),22 use_service_session=True, service_session_id_from_thread_id=True)) ← keeps no thread state23 │ OpenAI Responses + Entra token (https://ai.azure.com/.default)24Foundry hosted agent ResponsesHostServer(Agent(tools=[...])) ← deployed with azd25```2627**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.2829## Use the platform first3031Before you write any plumbing, check this table. Each row is something older codebases built by hand.3233| Need | Native primitive (don't hand-roll) |34| --- | --- |35| Conversation history across turns and restarts | Foundry **conversations**: create one per chat, use its `conv_…` ID as the AG-UI thread ID, and the gateway passes it through (no snapshot store) |36| Durable tool approvals | `ResponsesHostServer` persists approval requests by default (`FoundryFunctionApprovalStore`). The AG-UI adapter turns them into AG-UI interrupts and forwards decisions back to the hosted agent |37| Runs that survive browser disconnects | Responses `background: true` + `store: true`, then poll or reconnect (see [wiring](references/wiring.md#background-runs-gateway)) |38| Durable multi-step workflows with gates | Invocations hosted agent + `@multi_turn_task` + `FoundryStateStore` |39| Per-user files for the agent | Session Files API; the agent reads `$HOME` with its own tools. Never inline large documents into the prompt |40| Long-term user memory | Foundry Memory Store (user scope) or `FoundryMemoryProvider` |41| Tool catalogs, web search, code interpreter | Foundry **Toolbox** (`FoundryToolbox`) with Tool Search, instead of listing every tool up front |42| Live docs while coding | The Microsoft Learn and Foundry MCP servers (bundled with this skill's plugin) |4344## Choose the wiring4546| If the app needs… | Use | Gateway size |47| --- | --- | --- |48| Hosted agent + chat + tools + approvals (**default**) | **A. AG-UI gateway over a Responses hosted agent** | ~50 lines of Python |49| Every state pattern, local prototype, no Foundry compute | **B. In-process AG-UI** (agent runs inside the FastAPI app) | ~15 lines |50| Background runs that keep going after disconnect, reconnect, per-user conversation lists | **C. Background-runs gateway** (custom AG-UI agent over Foundry conversations) | ~150 lines of TypeScript |51| Multi-step plan → approve → execute, irreversible steps that must not run twice | **D. Invocations hosted agent** alongside A or C | REST proxy |5253Code for each is in [references/wiring.md](references/wiring.md). In an existing codebase, identify the wiring before you change anything:54- `FoundryAgent(...)` wrapped by `add_agent_framework_fastapi_endpoint` means A.55- `Agent(client=...)` wrapped directly means B.56- A custom `AbstractAgent` calling `/responses` with `background` means C.57- `protocol: invocations` in `azure.yaml` means D.5859## Workflow60611. **Pick or identify the wiring** (table above).622. **Use the latest release of every package** (`@copilotkit/*`, `@ag-ui/*`, `agent-framework-*`, `azd` and its `azure.ai.agents` extension). Then ground on live sources:63 - the Microsoft Learn MCP server for MAF and Foundry64 - the Foundry MCP server for project state65 - docs.copilotkit.ai and the `.d.ts` files bundled in the installed `@copilotkit/*` packages66 - docs.ag-ui.com6768 APIs move between minor versions, so don't trust memorized names.693. **Build or change it** with a playbook below.704. **Verify adversarially** against the completion criteria. A compiling build, a started server, or one good chat reply is not proof.7172## Playbooks7374### Build a new app end to end (wiring A)75761. 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](references/wiring.md#1-hosted-agent)).772. Run it locally with `azd ai agent run` (port 8088) and smoke-test it with `azd ai agent invoke --local "hi"`.783. `azd deploy` (each deploy creates a new agent version), then `azd ai agent invoke "hi"`.794. Add the AG-UI gateway exactly as in [wiring §2](references/wiring.md#2-ag-ui-gateway-wiring-a), 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.805. Add the conversation route, the CopilotKit runtime route and the React provider ([wiring §3](references/wiring.md#3-copilotkit-runtime-and-react)).816. Add `useInterrupt` approval UI and a tool renderer ([hitl.md](references/hitl.md#frontend-copilotkit-v2)).827. Verify every completion criterion, first locally and then against the deployed agent.8384### Add or change an agent tool85861. Define it with `@tool` (Python) or `AIFunctionFactory.Create` (.NET), using typed and described parameters.872. Keep parameter descriptions free of concrete example values for data the model must derive. Models copy literal examples.883. Return compact values. Rich formatting belongs in the UI renderer.894. Side-effecting tools get `approval_mode="always_require"` ([hitl.md](references/hitl.md)).905. Redeploy the hosted agent. Tools live in the hosted agent, not the gateway.916. Verify through the UI that `TOOL_CALL_*` events stream, and that any component parsing the arguments still works.9293### Generative UI and shared state (CopilotKit v2 hooks)9495| Pattern | Agent side | Frontend hook |96| --- | --- | --- |97| Frontend tool (agent calls the UI) | none; arrives in `RunAgentInput.tools` | `useFrontendTool` |98| Render a backend tool call | normal `@tool` | `useRenderTool` / `useRenderToolCall` / `useDefaultRenderTool` |99| Human approval of a tool call | `approval_mode="always_require"` | `useInterrupt` → `resolve({approved})` |100| Agent asks the user for input (frontend-resolved tool) | none | `useHumanInTheLoop` → `respond(...)` |101| Shared or predictive state | `state_schema` / `predict_state_config` on `AgentFrameworkAgent` | `useAgent` (read `agent.state`) |102103State patterns emit `STATE_SNAPSHOT`/`STATE_DELTA` only when the adapter can see the agent's state:104- **Wiring B** gets them natively.105- **Wiring A** needs them declared on the gateway's `AgentFrameworkAgent`. Test this before you promise the feature.106- **Wiring C** has no state events unless you synthesize them.107108### Debug a broken flow109110Work from the lowest layer upward:1111. Call the hosted agent with `azd ai agent invoke` or `curl` against `/responses`.1122. Call the gateway with a real conversation ID. A made-up thread ID returns HTTP 500 with this wiring:113114 ```bash115 CONV=$(curl -s -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents/$FOUNDRY_AGENT_NAME/endpoint/protocols/openai/conversations?api-version=v1" \116 -H "Authorization: Bearer $(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)" \117 -H 'content-type: application/json' -d '{}' | jq -r .id)118 curl -N -X POST <gateway>/ -H 'content-type: application/json' -d '{"threadId":"'$CONV'","runId":"r1","messages":[{"id":"m1","role":"user","content":"hi"}],"tools":[],"context":[],"state":{},"forwardedProps":{}}'119 ```1203. Test the CopilotKit route.1214. Test the browser.122123The first layer that fails owns the bug. Then match the symptom in [troubleshooting.md](references/troubleshooting.md). Use `azd ai agent monitor` for hosted-agent logs.124125### Upgrade dependencies126127Follow the version rules in [troubleshooting.md](references/troubleshooting.md#upgrades). Upgrade all packages together, then re-run the completion criteria live.128129## Completion criteria130131A change is done only when all of these hold:1321. The chat path works through the real UI, not only through curl.1332. Every approval-gated tool was tested both ways:134 - Approve: the tool runs once on the server and the side effect is observable.135 - Reject: the tool does not run, and the agent acknowledges it.1363. After an approval, a follow-up turn in the same thread does **not** re-run the gated tool.1374. Tool and approval cards still render after `RUN_FINISHED`, not only while streaming.1385. For deployed changes, checks 1–4 passed against the deployed agent and gateway. A successful deployment proves nothing about behavior.