Deploy a Foundry Agent

Provision Azure resources when needed, deploy the agent, and smoke-test it.

For hosted agents (custom container or code), use azd deploy. Prefer direct code deployment through azd (no Docker/ACR required): agent.yaml must contain code_configuration:, so azd deploy will use direct code deployment and zip the source and let Foundry build it. Use container/ACR deployment only when the agent truly needs a Dockerfile, custom system packages, or a pre-built image.

For prompt agents (LLM + instructions, no custom code), use the Foundry MCP agent_update tool.

Quick Reference

Hosted vs Prompt

• Shipping Python / .NET / Node code -> Hosted (azd workflow below).
• Updating only model / instructions / tools -> Prompt (MCP workflow below).

Deployment Method Selection -- Hosted agents

Before running azd deploy, inspect <service-dir>/agent.yaml.

code_configuration: example in agent.yaml:

code_configuration:
  runtime: python_3_13
  entry_point: main.py
  dependency_resolution: remote_build

Default to direct code for standard hosted-agent code. If azd deploy prints Packaging container for an agent that does not need container-specific behavior, add or fix code_configuration and retry. Use the container path when the agent depends on Dockerfile behavior, system packages, or a pre-built image.

Workflow -- Hosted agent (azd)

Prerequisite: project scaffolded with azd ai agent init. If not, start at create-hosted.

Step 1 -- Resolve azd environment

If the user provided an existing project endpoint, project ARM ID, or model deployment, set those values before deploy. Then verify the azd environment with azd env get-values.

azd env set AZURE_AI_PROJECT_ENDPOINT "<project-endpoint>"
azd env set AZURE_AI_PROJECT_ID "<project-arm-id>"
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "<model-deployment-name>"
azd env get-values

Run:

azd ai project show --output json
azd ai agent show --output json

Branch on output: not_deployed -> Step 2. active / deployed -> redeploy (skip Step 2, go to Step 3). If azd ai project show fails with missing_project_endpoint, do Step 2 first -- azd provision will create the project.

Important: Before deploy, also make sure agent.yaml and the azd environment are aligned with the user's provided configuration values.

Step 2 -- Provision Azure resources (one-time per env)

Skip azd provision when the user gave you an existing AZURE_AI_PROJECT_ENDPOINT or FOUNDRY_PROJECT_ENDPOINT and the workflow only needs to deploy the agent into that project.

Run provision only for new projects or real infrastructure changes:

azd provision --no-prompt

Optional: run azd provision --preview --no-prompt first to preview the resource changes (a what-if) before applying them.

What this does:

• Creates the Foundry project (if not present) and supporting resources under infra/.
• Creates project connections declared in azure.yaml services.<name>.config.connections[]. ${PARAM_*} placeholders resolve from the active azd env.
• Wires model deployments, AI Search, ACR, etc. infra/layers/ provision in parallel when present.

This is a core azd command. Skip provision when the user gave you an existing AZURE_AI_PROJECT_ENDPOINT via azd env set -- the extension uses the existing project as-is.

After provision completes for a new project, run azd env get-values and set missing required azd env values, especially AZURE_AI_PROJECT_ID and AZURE_TENANT_ID, before local run or the first azd deploy.

Step 3 -- Deploy the agent

azd deploy --no-prompt
# Multi-service:
azd deploy <service-name> --no-prompt

What deploy does:

• Reads <service-dir>/agent.yaml, packages the agent, uploads it, and registers a new immutable version.
• Direct code deploy (code_configuration present): zips source, excludes .agentignore, and lets Foundry build the runtime image.
• Container deploy (no code configuration): builds the Dockerfile, pushes to the project's ACR, registers the version. When agent.yaml has image: set, azd reuses the pre-built image.

After deploy, azd writes AGENT_<SVC>_NAME, AGENT_<SVC>_VERSION, and AGENT_<SVC>_<PROTO>_ENDPOINT (one per protocol) into the active env.

Re-deploying an identical build still creates a new version; azd prints Agent version <n> is already active. and skips the poll.

If deploy reports Done for the service and then fails only in postdeploy with Agent <service-name> with version <n> not found, the service key and agent.yaml name were mismatched. Rename the azure.yaml services key to the deployed agent name and rerun azd deploy --no-prompt; do not switch deployment method.

Step 4 -- Verify and invoke

azd ai agent show --output json

Expect "status": "active" (or "deployed") and an agent_endpoints map. Smoke-test:

azd ai agent invoke "hello, are you up?"

azd ai agent invoke is billed, so it prints a confirmation envelope on --no-prompt. Summarize changes[], then run confirmCommand once consented.

Run one remote invocation only unless the user explicitly asked to test multi-turn/session behavior. A single successful response is enough for the deployment smoke test. Anything other than a completed/successful response -> run azd ai agent doctor --output json, then follow troubleshoot.

Step 5: Auto-Generate Evaluation Suite (MANDATORY — RUNS AUTOMATICALLY)

⚠️ Pre-summary gate. If you are about to write a deployment summary or Playground link and Step 5 has not run, you are violating this skill. Run Step 5 first.

This step runs automatically after deploy. Ask the user which source to use and start it right after deploy succeeds — with --no-wait, generate returns in seconds and generation runs server-side, so it overlaps with invoke/test steps and finishes faster overall.

*"Your agent is deployed. Want me to set up an evaluation suite now? (a) Yes — current agent instructions (synthetic Q&A), (b) Yes — historical traces (last 3 days), (c) Yes — use existing eval.yaml, (d) No / later."*

Other useful flags on generate: --dataset <path-or-name> to reuse an existing dataset instead of generating one, --evaluator <name> (repeatable) to pin built-in or custom evaluators, --eval-model <name> to choose the model used for generation and evaluation, --reset-defaults to overwrite an existing eval config, --name <suite-name> and --out-file <path> (default eval.yaml).

Then proceed to Step 6. See After Deployment — Auto-Generate Evaluation Suite for run/refresh details.

Step 6 -- Hand off

• Send more messages -> invoke
• Evaluate / optimize -> observe
• Diagnose failures -> troubleshoot
• Search traces / latency -> trace

.agentignore

azd ai agent init writes a default <service-dir>/.agentignore for code-deploy projects (gitignore syntax) that excludes tooling files, secrets, language artifacts, and Docker files from the deploy ZIP. Only the root file is read; use !path to force-include.

Endpoint or card edits -- no new version

When only agentEndpoint: or agentCard: changed in agent.yaml:

azd ai agent endpoint update --dry-run # preview
azd ai agent endpoint update --force # apply

Idempotent.

Multi-environment deploys

azd env list
azd env select prod
azd deploy --no-prompt

Each env has its own AGENT_<SVC>_* vars.

Common failure modes -- Hosted

For deeper logs, see troubleshoot.

Workflow -- Prompt agent (MCP)

Prompt agents are not containerized -- they are a model + instructions + optional tools, created through the Foundry MCP server. Use when the user explicitly wants a prompt agent.

MCP tools

Steps

1. Collect config -- resolve endpoint from azd env get-values or ask. Then ask for agent name, model deployment (e.g. gpt-4o), and optional instructions, temperature, tools.
2. Get schema -- agent_definition_schema_get with schemaType: "prompt".
3. Create -- agent_update with {"kind": "prompt", "model": "<deployment>", "instructions": "...", "temperature": 0.7}.
4. Smoke test -- follow invoke.
5. Auto-generate evaluation suite -- see Step 5: Auto-Generate Evaluation Suite (Prompt) below.
6. Hand off -- evaluate via observe; clone via agent_update + isCloneRequest; delete via agent_delete.

Step 5: Auto-Generate Evaluation Suite (Prompt) (MANDATORY — RUNS AUTOMATICALLY)

⚠️ Pre-summary gate. If you are about to write a deployment summary or Playground link and Step 5 has not run, you are violating this skill. Run Step 5 first.

This step runs automatically after deploy. Ask the user which source to use and start it right after deploy succeeds — with --no-wait, generate returns in seconds and generation runs server-side, so it overlaps with invoke/test steps and finishes faster overall.

*"Your agent is deployed. Want me to set up an evaluation suite now? (a) Yes — current agent instructions (synthetic Q&A), (b) Yes — historical traces (last 3 days), (c) Yes — use existing eval.yaml, (d) No / later."*

Common failure modes -- Prompt

Display agent details (both flows)

After a successful deploy, show the agent's name, version, status, and endpoints in a table. Include a Playground link:

https://ai.azure.com/nextgen/r/{encodedSubId},{resourceGroup},,{accountName},{projectName}/build/agents/{agentName}/build?version={agentVersion}

encodedSubId is the subscription GUID as URL-safe base64 (no =):

python -c "import base64,uuid;print(base64.urlsafe_b64encode(uuid.UUID('<SUBSCRIPTION_ID>').bytes).rstrip(b'=').decode())"

For hosted agents, playground_url is in azd ai agent show --output json.

After Deployment — Auto-Generate Evaluation Suite

Reference for Step 5 options (a) and (b) — start generate right after deploy so its server-side generation overlaps with invoke/test steps and finishes faster. Options (c) and (d) skip generate and go straight to section 3 (run) or stop.

1. Inspect existing eval.yaml

Check the selected agent root for eval.yaml:

• Exists and matches the selected agent → skip generate; go to step 3 (run).
• Missing or stale → continue to step 2.

2. Submit generation (asynchronous, server-side)

Run azd ai agent eval generate --no-wait with the user's chosen flags (see the Step 5 table). The command:

• Submits dataset + evaluator generation jobs server-side.
• Returns in seconds.
• Writes pending operation IDs to local azd state.
• Writes a placeholder eval.yaml at the agent root (override with --out-file <path>).

No skill-side polling, terminal handle, or later-turn re-check is needed. azd ai agent eval run (section 3) automatically resumes a pending generation, downloads artifacts, finalizes eval.yaml, then runs the eval.

If the user wants to wait synchronously instead (e.g., to inspect eval.yaml before running), drop --no-wait — generate will then submit the jobs, wait for completion, download review artifacts, and write the finalized eval.yaml before returning (typically several minutes).

3. Run the suite

azd ai agent eval run

Use azd ai agent eval show -O results.json to inspect run details, or azd ai agent eval list to see history.

4. Refresh datasets/evaluators (later)

When local files under datasets/<suite>/ or evaluators/<suite>/ change, run azd ai agent eval update --dataset-only or --evaluator-only to upload new versions. azd bumps the version fields in eval.yaml.

5. Prompt User

*"Your agent is deployed and evaluation suite generation is submitted server-side (still running, takes several minutes). Would you like to run an evaluation now? azd ai agent eval run will wait for generation to finish, then execute the eval."*

• Yes → run azd ai agent eval run (this resumes the pending generation, then runs the eval — may take several minutes the first time), then follow the observe skill to interpret results.
• No → stop. The user can return later via azd ai agent eval run — it will pick up wherever the pending generation is.
• Production trace analysis → follow the trace skill.

Non-Interactive / YOLO Mode

• Hosted: always pass --no-prompt. If azd ai agent invoke prints a confirmation_required envelope, summarize changes[] and re-run with --force after the user consents -- never auto-append --force.
• Prompt: all required values (project endpoint, agent name, model deployment) must come from the user message or azd env get-values; missing values should fail loudly rather than prompt.