AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/azd-guidance/references/azd-ai-cli.md

azd ai CLI Reference

Core mental model for the azd ai agent extension. Use this when you need to understand command surface, file layout, or where a given setting lives.

CLI surface

azd ai project show                  # which Foundry project endpoint is active
azd ai agent show                    # is the agent deployed? what version?
azd ai agent doctor                  # full health check, suggests fixes

azd ai agent sample list             # curated catalog -- pick a manifestUrl
azd ai agent init -m <manifestUrl>   # scaffold from a sample
azd ai agent init --src <dir>        # scaffold from existing source

azd ai agent run --no-client         # start on localhost:8088 without a client UI
azd ai agent run                     # start and open the protocol-appropriate client
azd ai agent invoke "<msg>"          # invoke the deployed agent
azd ai agent invoke --local "<msg>"  # invoke the agent on localhost

azd provision                        # core azd; creates Foundry project + infra
azd deploy                           # core azd; packages + registers new agent version
azd ai agent endpoint update         # patch agentEndpoint / agentCard in place

azd ai connection list / show / create / update / delete
azd ai toolbox list / show / create / publish / delete
azd ai toolbox connection add / remove / list
azd ai toolbox versions list

azd ai agent files upload / download / list / delete / mkdir / stat
azd ai agent sessions create / show / stop / delete / list
azd ai agent monitor                 # per-session log stream (SSE)

azd ai agent eval generate / run / show / update / list
azd ai agent optimize / optimize status / optimize apply / optimize deploy / optimize cancel

Use --output json only when a command supports it. azd ai agent invoke supports default and raw output.

Without --no-client, azd ai agent run opens Agent Inspector for the Responses and Invocations protocols, or Microsoft 365 Agents Playground for the Activity protocol. azd ai agent invoke does not support the Activity protocol; use the Playground locally and the configured Microsoft 365 channel after deployment.

Hosted files and sessions

Use the file commands for an active hosted-agent session:

| Command | Purpose | |---------|---------| | azd ai agent files upload | Upload a local file. | | azd ai agent files download | Download a remote file. | | azd ai agent files list | List a remote directory. | | azd ai agent files stat | Inspect metadata for a remote path. | | azd ai agent files mkdir | Create a remote directory. | | azd ai agent files delete | Delete a remote file or directory. |

Directory deletion is not recursive by default. Add --recursive only when deleting the directory and all of its contents is intentional.

azd ai agent invoke manages the current session automatically. It reuses the saved session for the agent or captures and persists the server-assigned session on the first invoke. Use --new-session to reset session-backed state or --session-id to select a known session.

Use sessions create only when a session must exist before invoke or file operations. The remaining session commands are show, stop, delete, and list. sessions stop stops compute and preserves the session filesystem. sessions delete removes both compute and filesystem state. See Hosted Session Management.

The azure.yaml service block

After azd ai agent init, each agent developed through azd is defined as a service block in azure.yaml (host: azure.ai.agent) plus the active azd env. Hosted Agents add code/container fields; new Managed Harness Agent authoring uses kind: prompt and harness.type: microsoft_copilot_preview.

| Location | What it holds | |------|---------------| | azure.yaml services.<name> (the agent) | host: azure.ai.agent, kind, name, project, language, uses, protocols, environmentVariables, codeConfiguration / docker / image, container.resources, description, agentEndpoint, agentCard, startupCommand. | | azure.yaml services.ai-project | Model deployments[] (host: azure.ai.project). The agent links to it via uses: [ai-project]. | | .azure/<env>/.env (azd env set) | Secrets and PARAM_<CONN>_<KEY> credential values referenced from azure.yaml. |

azd deploy reads the agent service block and creates a new immutable agent version. azd provision reads project infrastructure such as services.ai-project.deployments[] and applies it via Bicep.

agent.manifest.yaml (the file passed to -m) is the seed format -- it is NOT on disk after init. Init folds its parameters: / resources: blocks into the azure.yaml service block and the azd env.

Local vs API field names. Local azure.yaml uses camelCase (codeConfiguration, entryPoint, dependencyResolution, environmentVariables). The deployed definition returned by azd ai agent show / the Foundry agent_get API uses snake_case (code_configuration, entry_point as an array, environment_variables). Don't mix the two.

Hosted agent service block (code deploy)

services:
  ai-project:
    host: azure.ai.project
    deployments:
      - name: gpt-4.1-mini
        model:
          format: OpenAI
          name: gpt-4.1-mini
          version: "2024-04-09"
        sku:
          name: GlobalStandard
          capacity: 50
  my-agent:
    project: src/my-agent
    host: azure.ai.agent
    language: python
    uses:
      - ai-project
    kind: hosted
    name: my-agent
    description: A hosted agent.
    codeConfiguration:
      runtime: python_3_13
      entryPoint: main.py
      dependencyResolution: remote_build   # or "bundled"
    container:
      resources:
        cpu: "0.5"
        memory: 1Gi
    environmentVariables:
      - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
        value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
    protocols:
      - protocol: responses
        version: 1.0.0
  • protocols -- responses, invocations, invocations_ws, or activity. Editing requires azd deploy.
  • container.resources -- valid tiers: 0.25/0.5Gi, 1/2Gi, 2/4Gi.
  • environmentVariables -- ${VAR} resolves from the active azd env. Not for secrets.
  • codeConfiguration present -> code deploy (ZIP, Foundry builds).
  • agentEndpoint / agentCard -- patch in place with azd ai agent endpoint update (no new version).
  • deployments[] (under the ai-project service) -- model deployments provisioned via Bicep. name is the literal Azure deployment resource name the agent references through AZURE_AI_MODEL_DEPLOYMENT_NAME.
  • Hosted connections/toolboxes -- created with azd ai connection / azd ai toolbox and consumed via a TOOLBOX_ENDPOINT env var (see toolbox.md).

Managed Harness Agent service block

services:
  assistant:
    host: azure.ai.agent
    kind: prompt
    name: assistant
    model: gpt-5-mini
    instructions: Help the user.
    harness:
      type: microsoft_copilot_preview
    tools:
      - type: web_search

A Managed Harness Agent has no source/runtime/container fields and no local azd ai agent run path. Direct Prompt Agent tools are authored in tools[]. Existing definitions may use legacy github_copilot_preview; azd recognizes both families and preserves the authored harness/toolset values. In this workflow, an existing Toolbox is attached through its exact versioned MCP endpoint plus a matching RemoteTool / UserEntraToken project connection (audience: https://ai.azure.com); existing Skills are referenced by name and version. Connection, Toolbox, and Skill resources are managed separately with their azd ai commands.

Voice Agent service blocks (kind: voice)

Use azd ai agent init --kind prompt-voice for a new Prompt Voice service. For Hosted Voice, initialize from an azure.yaml template that defines both the hosted target and Voice wrapper, or add a Voice wrapper to an existing compatible hosted target.

azd ai agent init --no-prompt --kind prompt-voice --agent-name <agent-name> \
  --model gpt-realtime

Resolve the new-versus-existing project choice before init and pass --project-id for an existing project. Normalize the generated YAML as directed by create-voice, then load only its selected subtype reference.

State (azd env vars)

| Variable | Read by | Where to set | |----------|---------|--------------| | AZURE_AI_PROJECT_ENDPOINT | Every azd ai agent command | azd env set | | AZURE_AI_PROJECT_ID | azd ai agent show (playground URL) | azd env set | | AZURE_SUBSCRIPTION_ID, AZURE_LOCATION | azd provision | Always set with azd env set ... immediately after init | | AGENT_<SVC>_NAME / _VERSION / _<PROTO>_ENDPOINT | Auto-written by deploy | Auto | | PARAM_<CONN>_<KEY> | Connection credentials in azure.yaml | azd env set |

Manage with azd env get-values, azd env set, azd env list, azd env new, azd env select.

The platform also injects FOUNDRY_* and AGENT_* into the running container at runtime. Never put these in the agent service's environmentVariables section.

Resolving subscription / location

azd ai project show returns only the Foundry project endpoint. For subscription / location, try in order:

  1. azd config get defaults
  2. azd env get-values
  3. Ask the user.
  4. Last resort, with explicit consent: az account list --output json.

For the Foundry project ARM ID (--project-id), ask the user: "New project, or use an existing one?" If existing, ask for the ID and hint where to find it (https://ai.azure.com -> Operate -> Admin). Do NOT shell out to az cognitiveservices -- it returns the wrong resource shape.

Common error codes

  • not_logged_in / login_expired -- ask the user to run azd auth login.
  • missing_project_endpoint -- run azd provision, or azd env set AZURE_AI_PROJECT_ENDPOINT <url>.
  • project_not_found -- cwd has no azure.yaml. Move to project root or run init.
  • invalid_agent_manifest -- the agent service block is malformed. Run azd ai agent doctor and read the named field.
  • invalid_connection -- inspect with azd ai connection show <name>.
  • eval_config_invalid -- eval.yaml failed validation. Run azd ai agent doctor.
  • agent_definition_not_found -- deployed name doesn't match azure.yaml. Re-deploy from project root.

Any unfamiliar code value is safe to surface verbatim to the user.