Setting the file. One moment.
Skill 172 · Foundry Hosted Agent Copilotkit
Subchapter 172.2
references/deploy-loop.mdMarkdown4 KBView on GitHub
Foundry hosted agents are defined by agent.yaml (identity: kind: hosted, model, protocols, environment variables, resources — schema at microsoft.github.io/AgentSchema/), optionally an (parameterized template), and (azd provisioning + service config). in these files is an azd environment variable; is an init-time template parameter.
agent.manifest.yamlazure.yaml${VAR}{{ param }}There is no mock. The azure.ai.agents azd extension runs the actual hosted agent locally:
az login into the tenant that owns the Foundry project (see the 403 trap below).azd ai agent run — starts the agent locally (default port 8088) against the provisioned project.azd ai agent invoke --local "<message>" — one-shot test (-p responses|invocations selects protocol, -f payload.json for structured input).Inner-loop discipline:
azd ai agent run — kill it first.DeploymentNotFound on the first request even though the model deployment exists (warm-up flake) — retry once before investigating.azd deploy (or azd up for provision + deploy). Code-deploy (ZIP) vs container-deploy is selected by fields in agent.yaml; container builds default to remote ACR builds — no local Docker needed.azd ai agent show confirms what’s live. Clients pinned to a specific version won’t see the update; clients using “latest” will.| Gotcha | Detail |
|---|---|
azd provision alone deploys a placeholder | Provision creates infrastructure only; without a deploy step you get a hello-world agent. Use azd up or follow provision with azd deploy |
| Base images must come from MCR | az acr build pulling from Docker Hub anonymously hits toomanyrequests rate limits. Use mcr.microsoft.com/... base images |
| Shared code missing from the image | If agent code imports modules outside the agent directory, the docker build context in azure.yaml must reach them — and azd versions have differed in whether they accept a parent-directory project:/context path (a 1.27.0-era regression rejected ..). Test packaging after azd upgrades |
| Hosted container env | FOUNDRY_PROJECT_ENDPOINT and APPLICATIONINSIGHTS_CONNECTION_STRING are injected automatically in hosted containers; don’t hardcode them |
| Compute idles out | Hosted agent compute deprovisions after ~15 minutes idle; first request after idle is slow — not a bug |
| History duplication (Responses protocol) | The platform stores conversation history; if the agent’s own chat client also stores (store=True), turns duplicate. Set the client/host options to not store |
| Bridge/front-door scaling | Any service holding per-thread response-id or conversation caches in memory must run a single replica or externalize the cache |
| Tenant-mismatch 403 | Microsoft.MachineLearningServices/workspaces/agents/action denied despite correct RBAC usually means the az CLI’s active subscription/tenant isn’t the project’s. Fix with az account set / az login --tenant; no code change |
Deploy the AG-UI endpoint (Architecture A/C service, or rely on the hosted invocations endpoint for B) where the CopilotKit runtime can reach it server-side; set the runtime’s agent URL env var accordingly. Keep auth keyless (Entra) with the https://ai.azure.com/.default audience. The browser talks only to the CopilotKit runtime route — never expose Foundry endpoints or credentials to the client.