1# azd ai CLI Reference
2 
3Core 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.
4 
5## CLI surface
6 
7```bash
8azd ai project show                  # which Foundry project endpoint is active
9azd ai agent show                    # is the agent deployed? what version?
10azd ai agent doctor                  # full health check, suggests fixes
11 
12azd ai agent sample list             # curated catalog -- pick a manifestUrl
13azd ai agent init -m <manifestUrl>   # scaffold from a sample
14azd ai agent init --from-code        # scaffold from existing source
15 
16azd ai agent run                     # start the agent on localhost:8088
17azd ai agent invoke "<msg>"          # remote invoke (billed; gated)
18azd ai agent invoke --local "<msg>"  # local invoke (no billing)
19 
20azd provision                        # core azd; creates Foundry project + infra
21azd deploy                           # core azd; packages + registers new agent version
22azd ai agent endpoint update         # patch agentEndpoint / agentCard in place
23 
24azd ai agent connection list / show / create / update / delete
25azd ai toolbox list / show / create / update / delete
26azd ai toolbox connection add / remove / list
27azd ai toolbox version list
28 
29azd ai agent files list / show / upload / download / delete / stat / mkdir
30azd ai agent sessions list / show / create / update / delete
31azd ai agent monitor                 # per-session log stream (SSE)
32 
33azd ai agent eval generate / run / show / update / list
34azd ai agent optimize / optimize status / optimize apply / optimize deploy / optimize cancel
35```
36 
37Read-only commands accept `--output json` and never require `--force`. Write commands are gated by a confirmation envelope (see "Confirmation envelope" below).
38 
39## Two files, two schemas
40 
41After `azd ai agent init`, every hosted agent is defined by **two** files plus the active azd env. Putting a field in the wrong file is the most common scaffolding failure.
42 
43| File | What it holds |
44|------|---------------|
45| `<service-dir>/agent.yaml` | The flat `ContainerAgent`: `kind`, `name`, `protocols`, `environment_variables`, `agentEndpoint`, `agentCard`, `code_configuration` / `image`, container `resources` (cpu, memory). |
46| `azure.yaml services.<name>.config` | Model deployments, project connections, toolboxes, tool resources, container settings, `startupCommand`. |
47| `.azure/<env>/.env` (`azd env set`) | Secrets and `PARAM_<CONN>_<KEY>` credential values referenced from `azure.yaml`. |
48 
49`azd deploy` reads `agent.yaml` and creates a new immutable agent version. `azd provision` reads `config.deployments[]` and `config.connections[]` and applies them via Bicep.
50 
51`agent.manifest.yaml` (the file passed to `-m`) is the seed format -- it is NOT on disk after init. Init splits its `parameters:` / `resources:` blocks across the three files above. Don't reintroduce the `template:` wrapper into `agent.yaml`.
52 
53### Minimal `agent.yaml` (hosted)
54 
55```yaml
56# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
57kind: hosted
58name: my-agent
59protocols:
60  - protocol: responses
61    version: "1.0.0"
62resources:
63  cpu: "0.25"
64  memory: "0.5Gi"
65environment_variables:
66  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
67    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
68code_configuration:
69  runtime: python_3_13
70  entry_point: app.py
71  dependency_resolution: remote_build   # or "bundled"
72```
73 
74- `protocols` -- `responses` (OpenAI), `invocations` (A2A). Editing requires `azd deploy`.
75- `resources` -- valid tiers: `0.25/0.5Gi`, `1/2Gi`, `2/4Gi`.
76- `environment_variables` -- `${VAR}` resolves from the active azd env. Not for secrets.
77- `code_configuration` present -> direct code deploy (ZIP, Foundry builds). Absent -> container/ACR deploy (Dockerfile + `docker:` in `azure.yaml`). `image:` skips the Dockerfile build.
78- In non-interactive mode, `azd ai agent init` defaults to container deploy. Pass `--deploy-mode code --runtime <runtime> --entry-point <file>` during init to get `code_configuration`.
79- `agentEndpoint` / `agentCard` -- patch in place with `azd ai agent endpoint update` (no new version).
80 
81### Minimal `azure.yaml` service config
82 
83```yaml
84services:
85  my-agent:
86    project: ./src/my-agent
87    host: azure.ai.agent
88    language: python
89    config:
90      startupCommand: "python -m main"
91      container:
92        resources:
93          cpu: "0.5"
94          memory: "1Gi"
95      deployments:
96        - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
97          model:
98            name: gpt-4.1-mini
99            format: OpenAI
100            version: "2024-04-09"
101          sku:
102            name: GlobalStandard
103            capacity: 50
104      connections: [...]        # see tools.md
105      toolboxes: [...]          # see tools.md
106```
107 
108- `startupCommand` -- what `azd ai agent run` executes locally. Auto-detected at init.
109- `config.container.resources` -- deployment-time CPU/memory. Keep this aligned with `agent.yaml resources`; this value can override the agent file.
110- `deployments[]` -- model deployments provisioned via Bicep. `name` is the env var the agent reads.
111- `connections[]` -- project connections provisioned via Bicep. Use `PARAM_<CONN>_<KEY>` env-var references for secrets.
112- `toolboxes[]` -- declarative record of intent; today you still drive the toolbox CLI to materialize them on Foundry. See [tools](tools.md).
113 
114## State (azd env vars)
115 
116| Variable | Read by | Where to set |
117|----------|---------|--------------|
118| `AZURE_AI_PROJECT_ENDPOINT` | Every `azd ai agent` command | `azd env set` or `azd ai project show` |
119| `AZURE_AI_PROJECT_ID` | `azd ai agent show` (playground URL) | `azd env set` |
120| `AZURE_SUBSCRIPTION_ID`, `AZURE_LOCATION` | `azd provision` | `azd config get defaults` |
121| `AGENT_<SVC>_NAME` / `_VERSION` / `_<PROTO>_ENDPOINT` | Auto-written by deploy | Auto |
122| `PARAM_<CONN>_<KEY>` | Connection credentials in `azure.yaml` | `azd env set` |
123 
124Manage with `azd env get-values`, `azd env set`, `azd env list`, `azd env new`, `azd env select`.
125 
126The platform also injects `FOUNDRY_*` and `AGENT_*` into the running container at runtime. **Never** put these in the agent.yaml environment_variables section.
127 
128## Resolving subscription / location
129 
130`azd ai project show` returns only the Foundry project endpoint. For subscription / location, try in order:
131 
1321. `azd config get defaults`
1332. `azd env get-values`
1343. Ask the user.
1354. Last resort, with explicit consent: `az account list --output json`.
136 
137For 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.
138 
139## Common error codes
140 
141- `not_logged_in` / `login_expired` -- ask the user to run `azd auth login`.
142- `missing_project_endpoint` -- run `azd provision`, or `azd env set AZURE_AI_PROJECT_ENDPOINT <url>`.
143- `project_not_found` -- cwd has no `azure.yaml`. Move to project root or run init.
144- `invalid_agent_manifest` -- `agent.yaml` is malformed. Run `azd ai agent doctor` and read the named field.
145- `invalid_connection` -- inspect with `azd ai agent connection show <name>`.
146- `eval_config_invalid` -- `eval.yaml` failed validation. Run `azd ai agent doctor`.
147- `agent_definition_not_found` -- deployed name doesn't match `azure.yaml`. Re-deploy from project root.
148 
149Any unfamiliar `code` value is safe to surface verbatim to the user.
150