Wiring

references/wiring.mdMarkdown18 KBView on GitHub

Wiring reference

Package names below are current as of late 2026. Always install the latest releases and verify names against the installed packages: Python via python -c "import agent_framework_ag_ui as m; print(m.__all__)", TypeScript via the .d.ts files.

Wiring · Foundry Hosted Agent Copilotkit · github/awesome-copilot · Skills Docs

azd ai agent init --no-prompt -e <env> -p <project-arm-id> -d <model-deployment> \
  --agent-name my-agent --protocol responses --deploy-mode code \
  --runtime python_3_13 --entry-point main.py --src src/my-agent
azd env get-values -e <env>   # FOUNDRY_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME and
                              # AZURE_LOCATION (= the project's region) must all be set

services:
  my-agent:
    project: src/my-agent
    host: azure.ai.agent
    language: python
    uses: [ai-project]
    env:
      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
    codeConfiguration: { runtime: python_3_13, entryPoint: main.py }
    protocols:
      - protocol: responses
        version: 2.0.0

import asyncio, os
from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

@tool
def get_balance(account: str) -> str:
    """Read-only lookup of an account balance."""
    ...

@tool(approval_mode="always_require")
def transfer(from_account: str, to_account: str, amount: float) -> str:
    """Move money. Side-effecting, so a human must approve it first."""
    ...

async def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],  # injected when hosted
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )
    agent = Agent(client=client, instructions="...", tools=[get_balance, transfer],
                  default_options={"store": False})  # the hosting layer owns history
    await ResponsesHostServer(agent).run_async()

if __name__ == "__main__":
    asyncio.run(main())

# gateway/app.py — run: uvicorn app:app --port 8000
import os
from ag_ui.core import EventType
from agent_framework.foundry import FoundryAgent
from agent_framework_ag_ui import AgentFrameworkAgent, add_agent_framework_fastapi_endpoint
from azure.identity.aio import DefaultAzureCredential
from fastapi import FastAPI


class HostedApprovalSafeAgent(AgentFrameworkAgent):
    """Interop fixes verified with agent-framework-ag-ui 1.4.0 + CopilotKit 1.76 / @ag-ui/client 1.0.1.

    1. CopilotKit sends an interrupt decision twice: as `resume` AND as a tool message keyed by
       the interrupt id. The duplicate makes the adapter skip the model's reply and leaves the
       Foundry conversation returning empty runs. Keep only `resume`.
    2. The adapter emits TOOL_CALL_END for the hosted approval id (`mcpr_...`) without a
       TOOL_CALL_START; @ag-ui/client aborts the run with INCOMPLETE_STREAM. Drop it.
    Delete this class when a release fixes both and the HITL regression test passes without it.
    """

    async def run(self, input_data, **kwargs):
        # The endpoint passes snake_case keys (interrupt_id, tool_call_id) by the time run() is called.
        resumed = {r.get("interrupt_id") or r.get("interruptId") or r.get("id")
                   for r in (input_data.get("resume") or []) if isinstance(r, dict)}
        if resumed:
            input_data = {**input_data, "messages": [
                m for m in input_data.get("messages", [])
                if not (m.get("role") == "tool" and (m.get("tool_call_id") or m.get("toolCallId")) in resumed)]}
        started: set[str] = set()
        async for event in super().run(input_data, **kwargs):
            if event.type == EventType.TOOL_CALL_START:
                started.add(event.tool_call_id)
            elif event.type == EventType.TOOL_CALL_END and event.tool_call_id not in started:
                continue
            yield event


hosted = FoundryAgent(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    agent_name=os.environ["FOUNDRY_AGENT_NAME"],   # same name as in azure.yaml
    credential=DefaultAzureCredential(),
    allow_preview=True,                             # hosted-agent session APIs are preview
)
app = FastAPI()
add_agent_framework_fastapi_endpoint(
    app,
    HostedApprovalSafeAgent(agent=hosted, use_service_session=True,
                            service_session_id_from_thread_id=True),  # threadId == Foundry conv_ id
    "/",
)

import { HttpAgent } from "@ag-ui/client";
import { CopilotRuntime, createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";

const runtime = new CopilotRuntime({
  agents: { default: new HttpAgent({ url: process.env.AGUI_URL! }) }, // gateway URL
});
const handler = createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit" });
export const GET = handler;
export const POST = handler;

import { DefaultAzureCredential } from "@azure/identity";

const credential = new DefaultAzureCredential();

export async function POST() {
  const { token } = await credential.getToken("https://ai.azure.com/.default");
  const url = `${process.env.FOUNDRY_PROJECT_ENDPOINT}/agents/${process.env.FOUNDRY_AGENT_NAME}` +
    `/endpoint/protocols/openai/conversations?api-version=v1`;
  const res = await fetch(url, {
    method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: "{}",
  });
  if (!res.ok) return Response.json({ error: `Foundry ${res.status}` }, { status: 502 });
  const { id } = (await res.json()) as { id: string };   // conv_...
  return Response.json({ threadId: id });                 // multi-user: record (user, id) here
}

"use client";
import { useEffect, useState } from "react";
import { CopilotKitProvider, CopilotChat, useDefaultRenderTool } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";
import { ApprovalUI } from "./approval";   // useInterrupt, see hitl.md

function ToolRows() {
  // Hosted tools run remotely; without a renderer their results are invisible in the chat.
  useDefaultRenderTool({
    render: ({ name, result }) => name === "confirm_changes" ? null :
      <div>{name}: {typeof result === "string" ? result : JSON.stringify(result ?? "")}</div>,
  });
  return null;
}

export default function Page() {
  const [threadId, setThreadId] = useState<string>();
  const [error, setError] = useState<string>();
  useEffect(() => {
    fetch("/api/thread", { method: "POST" })
      .then(async (r) => {
        const d = await r.json().catch(() => ({}));
        if (!r.ok || typeof d.threadId !== "string" || !d.threadId.startsWith("conv_")) {
          throw new Error(d.error ?? `Could not start a conversation (HTTP ${r.status})`);
        }
        setThreadId(d.threadId);
      })
      .catch((e: unknown) => setError(e instanceof Error ? e.message : String(e)));
  }, []);
  if (error) return <p role="alert">{error}</p>;
  if (!threadId) return <p>Starting conversation…</p>;
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit">
      <ToolRows />
      <ApprovalUI />
      <CopilotChat agentId="default" threadId={threadId} />
    </CopilotKitProvider>
  );
}

Step	Call
New thread	`POST {openai}/conversations` → `conversation.id`; `POST {agentEndpoint}/sessions` → `agent_session_id`; store `{threadId → conversationId, sessionId, owner}`
Start a turn	`POST {openai}/responses` `{input, conversation, agent_session_id, background: true, store: true, stream: false}` → save `response.id`
Stream to the UI	Poll `GET {openai}/responses/{id}` about once a second while `status ∈ {queued, in_progress}`. Emit `MESSAGES_SNAPSHOT` built from `GET {openai}/conversations/{id}/items` (paginate with `after` until `has_more` is false) merged with `response.output`. Finish with `RUN_FINISHED`, or `RUN_ERROR` carrying `response.error`
Reconnect	Same poll loop starting from the saved `response.id`. Disconnecting must not cancel the run
Cancel	`POST {openai}/responses/{id}/cancel`

azd ai agent run                       # the real agent on http://localhost:8088, using your az login
azd ai agent invoke --local "hi"       # smoke-test the local agent
azd deploy                             # code deploy; each deploy creates a new agent version
azd ai agent invoke "hi"               # call the deployed agent
azd ai agent show / monitor            # status and logs

Wiring

Wiring reference

Wiring

Wiring reference

2. AG-UI gateway (wiring A)

3. CopilotKit runtime and React

4. In-process AG-UI (wiring B)

5. Background-runs gateway (wiring C) {#background-runs-gateway}

6. Invocations workflow agent (wiring D)

7. Auth and identity

8. Local loop and deploy