1# Local Run Reference
2 
3Use this when iterating on a hosted agent before deploying.
4 
5> **Prerequisite:** Local run does NOT require `azd provision` or any deployed Azure infrastructure. The agent runs on your machine and calls the Foundry model endpoint directly using your local credentials (`DefaultAzureCredential` — falls back to `az login` / VS Code identity). You only need a `.env` file in the agent directory with:
6> ```env
7> FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
8> AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
9> ```
10> If you already ran `azd provision`, extract these from `azd env get-values`.
11>
12> 🚦 **If no project endpoint is configured (not in the message, `azd env`, or `.env`) and the user hasn't asked to create one, stop and ask them to pick an existing project or confirm creating a new one — don't silently select or `azd provision` one.** Once they choose, follow [deploy.md Step 2](../../deploy/deploy.md#step-2----provision-azure-resources-one-time-per-env) to provision or resolve the project, then return here for local iteration before deploying the agent.
13>
14> **Critical: keep `.env` and `azd env` in sync.** `azd ai agent run` injects the active `azd env` values into the agent process before Python loads `.env`. Many samples use `load_dotenv(override=False)`, so an existing process environment value wins over `.env`. If you change the project endpoint or model deployment, update both `.env` and `azd env`:
15> ```bash
16> azd env set FOUNDRY_PROJECT_ENDPOINT "https://<account>.services.ai.azure.com/api/projects/<project>"
17> azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "<model-deployment-name>"
18> azd env get-values
19> ```
20> A stale `AZURE_AI_MODEL_DEPLOYMENT_NAME` in `azd env` can make local run call the wrong deployment even when `.env` is correct, commonly surfacing as a Foundry responses API `404 Not Found`.
21 
22## Prepare the local environment
23 
24For Python agents, prepare the environment from the **agent's service source directory** -- the folder that contains `requirements.txt` and `agent.yaml` (typically `<repo>/src/<service-name>/`, not the azd project root). `azd ai agent run` resolves the venv relative to this folder; a `.venv` created in the project root is ignored and azd silently creates a second one without `uv`.
25 
261. `cd` into the service source directory.
272. Create a venv, for example `python -m venv .venv`.
283. Activate the venv.
294. Install `uv` inside the active venv: `python -m pip install uv`.
305. In the same shell with the service-dir `.venv` activated, run `azd ai agent run` (from any cwd in the project); it installs `requirements.txt` itself and uses `uv` from the active venv for faster Python dependency installation.
31 
32> **Important:** The venv must live next to `requirements.txt`, not in the azd project root. Install `uv` before running `azd ai agent run`, and keep that venv activated when running the command; otherwise the local run falls back to slower dependency installation. Do NOT manually run `pip install -r requirements.txt` / `uv pip install -r requirements.txt --prerelease=allow`; let `azd ai agent run` install dependencies.
33 
34## Start the agent locally
35 
36Activate the service-dir `.venv`, then in that venv run:
37 
38```bash
39azd ai agent run
40```
41 
42What this does:
43 
441. Resolves the agent service from `azure.yaml` (auto-picks when only one exists).
452. Detects the project type (Python, .NET, Node.js) from files in the service source dir.
463. Installs dependencies if needed. For Python, `azd ai agent run` installs `requirements.txt` itself and uses `uv` from the active local environment when available.
474. Starts the agent in the foreground on `localhost:8088` (default).
485. Opens **Agent Inspector** in your browser (unless `--no-inspector`).
49 
50> Wait for the ready log line before sending the first invocation. Poll the log at short intervals; do not pre-sleep on a fixed duration.
51 
52`Ctrl+C` stops the agent and clears the saved local session id in an interactive terminal.
53 
54For headless or CI runs, pass `--no-inspector` and start the local server in a managed background session that later steps can monitor and stop. Wait for the ready log line, invoke it from a second command, then stop the same background session before deploying or leaving a temporary workspace.
55 
56Do **not** start `azd ai agent run` as a detached process that you cannot monitor or stop (for example, a bare `azd ai agent run ... &`, or a popped PowerShell window on Windows). Keep logs, readiness polling, and the PID/process handle for cleanup.
57 
58## Useful flags
59 
60| Flag | Purpose |
61|------|---------|
62| `--port <n>` / `-p <n>` | Override the listen port. Useful when 8088 is taken. |
63| `--start-command "<cmd>"` / `-c "<cmd>"` | Override `azure.yaml` and auto-detect. Example: `--start-command "python app.py"`. |
64| `--no-inspector` | Skip opening Agent Inspector. Use in CI / SSH. |
65 
66Pass the service name when there are multiple `ai.agent` services:
67 
68```bash
69azd ai agent run my-agent
70```
71 
72## Where the start command comes from
73 
74Resolution order (first non-empty wins):
75 
761. `--start-command` flag.
772. `azure.yaml services.<name>.config.startupCommand`.
783. Auto-detected from project type.
79 
80Example:
81 
82```yaml
83# azure.yaml
84services:
85  my-agent:
86    project: src/my-agent
87    language: python
88    host: azure.ai.agent
89    config:
90      startupCommand: "uvicorn app:app --host 0.0.0.0 --port 4001"
91```
92 
93If detection fails and no override is set, `run` errors with the project dir and asks for `--start-command` or `startupCommand`.
94 
95## Invoke the local agent
96 
97```bash
98azd ai agent invoke --local "hello, are you up?"
99```
100 
101Do not use `--output json` with invoke. The invoke command supports `default` and `raw` output only.
102 
103If the user did not explicitly specify a prompt, use `"hello, are you up"` for the local smoke test; only verify that the agent can return a response.
104 
105Run one representative local invocation before deploying. If the local invocation returns a model `404` or wrong deployment error, check `azd env get-values` before changing code; stale azd env values are the most common cause.
106 
107`--local` differs from a remote invoke in:
108 
109- Targets `http://localhost:<port>` instead of the Foundry endpoint.
110- Skips the confirmation envelope (no billing, no remote mutation).
111- `--version` is rejected (versions are a remote concept).
112- Named-agent invocation is rejected (only one agent runs locally at a time).
113 
114Other useful flags:
115 
116| Flag | Purpose |
117|------|---------|
118| `--protocol responses` (default) / `--protocol invocations` | Wire format your agent speaks. |
119| `--input-file request.json` / `-f request.json` | Send a file body instead of a string message. |
120| `--new-session` | Drop the saved local session and start fresh. |
121| `--port <n>` | Match the port you started `run` with. |
122 
123After the local invocation completes, stop the `azd ai agent run` process you started before moving on.
124 
125## When to graduate to remote
126 
127Local dev validates code shape; remote validates infra + identity + Foundry binding. Move to deploy when:
128 
129- You changed `agent.yaml` `model:`, `tools:`, `connections:`, or `protocols:`. Those only take effect on the deployed agent.
130- You need to test against real Foundry connections (search indexes, Bing, MCP, A2A) that have no local mock.
131- You are ready to publish a new immutable agent version.
132 
133Before proceeding to deploy, clean up the local agent process.
134 
135Next step -> [deploy/deploy.md](../../deploy/deploy.md).
136 
137## Common failures
138 
139| Symptom | Likely cause | Fix |
140|---------|--------------|-----|
141| `could not connect to localhost:<port>` | `run` not started, or wrong port | Start `azd ai agent run`; pass `--port` to `invoke --local` if non-default. |
142| `could not detect project type in <dir>` | Missing project marker file | Set `startupCommand` in `azure.yaml` or pass `--start-command`. |
143| `cannot use --local with a named agent` | Named-agent invoke against localhost | Drop the name; only one local agent at a time. |
144| `cannot use --version with --local` | `--version` is remote-only | Drop `--version`, or remove `--local` to hit the deployed agent. |
145| Inspector never opens | Headless env, or extension install failed | Pass `--no-inspector`, or run `azd extension install azure.ai.inspector`. |
146| Auth / connection errors against Azure services | Local credentials not wired | Expected -- `DefaultAzureCredential` falls back to your `az login` / VS Code identity. Use `azd auth login` if needed. |
147