mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-14 10:01:06 +00:00
github-actions[bot]
42 lines
4.3 KiB
Markdown
42 lines
4.3 KiB
Markdown
# The hosted-agent development and deploy loop
|
|
|
|
Foundry hosted agents are defined by `agent.yaml` (identity: `kind: hosted`, model, protocols, environment variables, resources — schema at microsoft.github.io/AgentSchema/), optionally an `agent.manifest.yaml` (parameterized template), and `azure.yaml` (azd provisioning + service config). `${VAR}` in these files is an azd environment variable; `{{ param }}` is an init-time template parameter.
|
|
|
|
## Inner loop: develop against the REAL agent locally
|
|
|
|
There is no mock. The `azure.ai.agents` azd extension runs the actual hosted agent locally:
|
|
|
|
1. `az login` into the tenant that owns the Foundry project (see the 403 trap below).
|
|
2. `azd ai agent run` — starts the agent locally (default port 8088) against the provisioned project.
|
|
3. `azd ai agent invoke --local "<message>"` — one-shot test (`-p responses|invocations` selects protocol, `-f payload.json` for structured input).
|
|
4. Point the rest of the stack (AG-UI endpoint or bridge) at the local agent URL via whatever environment variable the codebase uses for direct/local mode, and exercise features through the real UI.
|
|
|
|
Inner-loop discipline:
|
|
|
|
- **Restart the agent between independent verification passes** if it seeds in-memory data — every approve/reject mutates shared state, so a second test run against a dirty process passes or fails for the wrong reason.
|
|
- A stale agent process holding the port produces a confusing hypercorn "Address already in use" traceback on the next `azd ai agent run` — kill it first.
|
|
- A freshly started agent can 404 with `DeploymentNotFound` on the first request even though the model deployment exists (warm-up flake) — retry once before investigating.
|
|
|
|
## Outer loop: deploy an update
|
|
|
|
1. `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.
|
|
2. **Each deploy creates a new agent version.** `azd ai agent show` confirms what's live. Clients pinned to a specific version won't see the update; clients using "latest" will.
|
|
3. Verify the deployed agent behaviorally: send a read query AND confirm a consequential action still pauses for approval. Deployment success output proves packaging worked, nothing more.
|
|
|
|
## Deploy gotchas
|
|
|
|
| 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 |
|
|
|
|
## Production frontend wiring
|
|
|
|
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.
|