Foundry Hosted Agent Copilotkit

Developing with CopilotKit + AG-UI + Azure AI Foundry Hosted Agents

Use this skill for development work inside an EXISTING application built on this stack: a React/Next.js frontend using CopilotKit, connected over the AG-UI protocol to a Microsoft Agent Framework (MAF) agent (Python or .NET) that runs as — or is being developed against — an Azure AI Foundry hosted agent (paid Azure service; usage may incur costs).

Do NOT use this skill to scaffold a new project. Dedicated scaffolders exist (the CopilotKit CLI, azd ai agent init); use those, then return here for everything that follows: adding tools, gating them behind approvals, generative UI, shared state, debugging, dependency upgrades, and deploying agent updates.

Mental model

CopilotKit hooks (React)            useFrontendTool / useHumanInTheLoop /
        │                           useRenderToolCall / useCoAgent
        ▼
CopilotKit Runtime (route handler)  agents: { <name>: new HttpAgent({ url }) }
        │  AG-UI events over SSE
        ▼
AG-UI endpoint                      ← WHERE this lives defines your architecture
        │
        ▼
MAF Agent (tools, approval modes)   → model deployment

The single most important fact: a deployed Foundry hosted agent endpoint does not speak AG-UI by default. It exposes an OpenAI Responses endpoint (.../protocols/openai/responses) and/or a raw .../protocols/invocations endpoint. AG-UI must be produced somewhere, and where it is produced determines how every feature (especially human-in-the-loop) behaves. The three wirings are described in references/architecture.md.

Workflow

Follow these steps for every task on this stack:

1. Identify the wiring first. Inspect the codebase before changing anything:
   • add_agent_framework_fastapi_endpoint(...) (Python) or MapAGUI(...) (.NET) wrapping an in-process agent → Architecture A (in-process AG-UI endpoint).
   • A hosted agent whose own container serves AG-UI, declared with protocol: invocations in agent.yaml → Architecture B.
   • A separate service translating between the AG-UI endpoint and a hosted agent's /responses endpoint (look for previous_response_id, mcp_approval_response, or a Foundry conversation object in the code) → Architecture C (translation bridge).
   • Confirm the frontend agent name: the key in the runtime agents config, the agent prop on the <CopilotKit> provider, and the hosted agent name in agent.yaml must all agree.
2. Ground in live documentation. Every layer here is pre-1.0 or preview and moves between minor versions. Never trust memorized APIs:
   • MAF and Foundry hosted agents: use the Microsoft Docs MCP tools when available, otherwise learn.microsoft.com (/agent-framework/integrations/ag-ui/, /azure/foundry/).
   • CopilotKit: docs.copilotkit.ai (Microsoft Agent Framework section). Verify hook and runtime API names against the TypeScript declarations bundled in the installed @copilotkit/* packages — names have churned (useCopilotAction is legacy; current names include useFrontendTool, useHumanInTheLoop, useRenderToolCall, useCoAgent).
   • AG-UI protocol: docs.ag-ui.com (event reference, dojo patterns).
3. Execute the task using the matching reference below.
4. Verify adversarially. A compiling build, a started dev server, or one successful chat reply is NOT proof. Apply the completion criteria at the end of this skill.

References

Load on demand; each is self-contained:

Task playbooks

Add or modify an agent tool

1. Define the tool on the agent (@tool in Python; AIFunctionFactory.Create in .NET) with typed, described parameters.
2. Keep docstrings grounding-safe: do not put concrete example values in parameter descriptions for fields the model must derive from real data — models copy literal examples. Use placeholders and validate inside the tool.
3. Return compact, model-consumable values; rich formatting belongs in the UI render, not the tool result.
4. Decide the approval mode now: side-effecting tools get approval_mode="always_require" (see references/hitl.md); read-only tools stay unrestricted.
5. If the tool call should render in the UI, add a useRenderToolCall/render entry for it (references/patterns.md).
6. Verify live: trigger the tool through the chat UI, confirm the call and result stream as TOOL_CALL_* events, and confirm renamed or re-typed parameters did not break any frontend component that parses the arguments.