Refactor foundry-agent documentation and tests

- Removed the direct-code deployment reference file as it is no longer needed.
- Added unit tests for the azd-based hosted-agent create workflow to ensure the new patterns are correctly implemented.
- Deleted outdated toolbox paths unit tests that referenced removed samples.
- Introduced unit tests for the azd-based hosted-agent deploy workflow to validate the new deployment process.
- Removed direct-code unit tests that were redundant after the removal of the direct-code deployment reference.

Author: therealjohn

plugin/skills/microsoft-foundry/SKILL.md

@@ -23,13 +23,13 @@ This skill includes specialized sub-skills for specific workflows. **Use these i
 
 | Sub-Skill | When to Use | Reference |
 |-----------|-------------|-----------|
-| **deploy** | Containerize, build, push to ACR, create/update/clone agent deployments | [deploy](foundry-agent/deploy/deploy.md) |
+| **deploy** | Deploy hosted agents with `azd provision` + `azd deploy`, smoke-test with `azd ai agent show`/`invoke`. Create or update prompt agents via the Foundry MCP `agent_update` tool. Manage versions, endpoint patches, multi-env deploys. | [deploy](foundry-agent/deploy/deploy.md) |
 | **invoke** | Send messages to an agent, single or multi-turn conversations | [invoke](foundry-agent/invoke/invoke.md) |
 | **invocations-ws** | Build, deploy, and connect to hosted agents that speak the `invocations_ws` duplex WebSocket protocol — voice agents, real-time streams, and signaling for out-of-band media transports. | [invocations-ws](foundry-agent/invocations-ws/invocations-ws.md) |
 | **observe** | Evaluate agent quality, run batch evals, analyze failures, optimize prompts, improve agent instructions, compare versions, set up CI/CD monitoring, and enable continuous production evaluation | [observe](foundry-agent/observe/observe.md) |
 | **trace** | Query traces, analyze latency/failures, correlate eval results to specific responses via App Insights `customEvents` | [trace](foundry-agent/trace/trace.md) |
 | **troubleshoot** | View hosted agent logs, query telemetry, diagnose failures | [troubleshoot](foundry-agent/troubleshoot/troubleshoot.md) |
-| **create** | Create new hosted agent applications. Supports Microsoft Agent Framework, LangGraph, or custom frameworks in Python or C#, across `responses`, `invocations`, or `invocations_ws` protocols. | [create](foundry-agent/create/create-hosted.md) |
+| **create** | Scaffold a hosted Foundry agent project with `azd ai agent init` -- greenfield from a curated sample, or brownfield from existing code (`--from-code`). Run + iterate locally with `azd ai agent run` and `azd ai agent invoke --local` before deploying. Add tools (web search, AI Search, MCP, A2A) via the toolbox workflow. | [create](foundry-agent/create/create-hosted.md) |
 | **agent-optimizer** | Make existing Python hosted-agent code optimization-ready, configure eval.yaml, run Agent Optimizer jobs, apply candidates locally, and deploy through azd after review. | [agent-optimizer](foundry-agent/agent-optimizer/agent-optimizer.md) |
 | **eval-datasets** | Harvest production traces into evaluation datasets, manage dataset versions and splits, track evaluation metrics over time, detect regressions, and maintain full lineage from trace to deployment. Use for: create dataset from traces, dataset versioning, evaluation trending, regression detection, dataset comparison, eval lineage. | [eval-datasets](foundry-agent/eval-datasets/eval-datasets.md) |
 | **project/create** | Creating a new Azure AI Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure. | [project/create/create-foundry-project.md](project/create/create-foundry-project.md) |

plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md

@@ -0,0 +1,149 @@
+# 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
+
+```bash
+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 --from-code        # scaffold from existing source
+
+azd ai agent run                     # start the agent on localhost:8088
+azd ai agent invoke "<msg>"          # remote invoke (billed; gated)
+azd ai agent invoke --local "<msg>"  # local invoke (no billing)
+
+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 agent connection list / show / create / update / delete
+azd ai toolbox list / show / create / update / delete
+azd ai toolbox connection add / remove / list
+azd ai toolbox version list
+
+azd ai agent files list / show / upload / download / delete / stat / mkdir
+azd ai agent sessions list / show / create / update / delete
+azd ai agent monitor                 # per-session log stream (SSE)
+
+azd ai agent eval init / run / show / update / list
+azd ai agent optimize / optimize status / optimize apply / optimize deploy / optimize cancel
+```
+
+Read-only commands accept `--output json` and never require `--force`. Write commands are gated by a confirmation envelope (see "Confirmation envelope" below).
+
+## Two files, two schemas
+
+After `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.
+
+| File | What it holds |
+|------|---------------|
+| `<service-dir>/agent.yaml` | The flat `ContainerAgent`: `kind`, `name`, `protocols`, `environment_variables`, `agentEndpoint`, `agentCard`, `codeConfiguration` / `image`, container `resources` (cpu, memory). |
+| `azure.yaml services.<name>.config` | Model deployments, project connections, toolboxes, tool resources, container settings, `startupCommand`. |
+| `.azure/<env>/.env` (`azd env set`) | Secrets and `PARAM_<CONN>_<KEY>` credential values referenced from `azure.yaml`. |
+
+`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.
+
+`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`.
+
+### Minimal `agent.yaml` (hosted)
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: my-agent
+protocols:
+  - protocol: responses
+    version: "1.0.0"
+resources:
+  cpu: "0.25"
+  memory: "0.5Gi"
+environment_variables:
+  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+codeConfiguration:
+  runtime: python_3_13
+  entryPoint: app.py
+  dependencyResolution: remote_build   # or "bundled"
+```
+
+- `protocols` -- `responses` (OpenAI), `invocations` (A2A). Editing requires `azd deploy`.
+- `resources` -- valid tiers: `0.25/0.5Gi`, `1/2Gi`, `2/4Gi`.
+- `environment_variables` -- `${VAR}` resolves from the active azd env. Not for secrets.
+- `codeConfiguration` present -> code deploy (ZIP, Foundry builds). Absent -> container deploy (Dockerfile + `docker:` in azure.yaml). `image:` skips the Dockerfile build.
+- `agentEndpoint` / `agentCard` -- patch in place with `azd ai agent endpoint update` (no new version).
+
+### Minimal `azure.yaml` service config
+
+```yaml
+services:
+  my-agent:
+    project: ./src/my-agent
+    host: ai.agent
+    language: docker            # or "python" / "csharp" for code deploy
+    docker:
+      remoteBuild: true         # omit for code deploy
+    config:
+      startupCommand: "python -m main"
+      container:
+        resources:
+          cpu: "0.5"
+          memory: "1Gi"
+      deployments:
+        - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+          model:
+            name: gpt-4.1-mini
+            format: OpenAI
+            version: "2024-04-09"
+          sku:
+            name: GlobalStandard
+            capacity: 50
+      connections: [...]        # see tools.md
+      toolboxes: [...]          # see tools.md
+```
+
+- `startupCommand` -- what `azd ai agent run` executes locally. Auto-detected at init.
+- `deployments[]` -- model deployments provisioned via Bicep. `name` is the env var the agent reads.
+- `connections[]` -- project connections provisioned via Bicep. Use `PARAM_<CONN>_<KEY>` env-var references for secrets.
+- `toolboxes[]` -- declarative record of intent; today you still drive the toolbox CLI to materialize them on Foundry. See [tools](tools.md).
+
+## State (azd env vars)
+
+| Variable | Read by | Where to set |
+|----------|---------|--------------|
+| `AZURE_AI_PROJECT_ENDPOINT` | Every `azd ai agent` command | `azd env set` or `azd ai project show` |
+| `AZURE_AI_PROJECT_ID` | `azd ai agent show` (playground URL) | `azd env set` |
+| `AZURE_SUBSCRIPTION_ID`, `AZURE_LOCATION` | `azd provision` | `azd config get defaults` |
+| `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.yaml environment_variables 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` -- `agent.yaml` is malformed. Run `azd ai agent doctor` and read the named field.
+- `invalid_connection` -- inspect with `azd ai agent 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.

plugin/skills/microsoft-foundry/foundry-agent/create/references/azd-ai-cli.md

@@ -0,0 +1,101 @@
+# Local Run Reference
+
+Use this when iterating on a hosted agent before deploying.
+
+## Start the agent locally
+
+```bash
+azd ai agent run
+```
+
+What this does:
+
+1. Resolves the agent service from `azure.yaml` (auto-picks when only one exists).
+2. Detects the project type (Python, .NET, Node.js) from files in the service source dir.
+3. Installs dependencies if needed (`uv pip install -e .`, `npm install`, `dotnet restore`).
+4. Starts the agent in the foreground on `localhost:8088` (default).
+5. Opens **Agent Inspector** in your browser (unless `--no-inspector`).
+
+> First startup takes 30-60 seconds. Wait before sending the first invocation.
+
+`Ctrl+C` stops the agent and clears the saved local session id.
+
+## Useful flags
+
+| Flag | Purpose |
+|------|---------|
+| `--port <n>` / `-p <n>` | Override the listen port. Useful when 8088 is taken. |
+| `--start-command "<cmd>"` / `-c "<cmd>"` | Override `azure.yaml` and auto-detect. Example: `--start-command "python app.py"`. |
+| `--no-inspector` | Skip opening Agent Inspector. Use in CI / SSH. |
+
+Pass the service name when there are multiple `ai.agent` services:
+
+```bash
+azd ai agent run my-agent
+```
+
+## Where the start command comes from
+
+Resolution order (first non-empty wins):
+
+1. `--start-command` flag.
+2. `azure.yaml services.<name>.config.startupCommand`.
+3. Auto-detected from project type.
+
+Example:
+
+```yaml
+# azure.yaml
+services:
+  my-agent:
+    project: src/my-agent
+    language: py
+    host: ai.agent
+    config:
+      startupCommand: "uvicorn app:app --host 0.0.0.0 --port 4001"
+```
+
+If detection fails and no override is set, `run` errors with the project dir and asks for `--start-command` or `startupCommand`.
+
+## Invoke the local agent
+
+```bash
+azd ai agent invoke --local "hello, are you up?"
+```
+
+`--local` differs from a remote invoke in:
+
+- Targets `http://localhost:<port>` instead of the Foundry endpoint.
+- Skips the confirmation envelope (no billing, no remote mutation).
+- `--version` is rejected (versions are a remote concept).
+- Named-agent invocation is rejected (only one agent runs locally at a time).
+
+Other useful flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--protocol responses` (default) / `--protocol invocations` | Wire format your agent speaks. |
+| `--input-file request.json` / `-f request.json` | Send a file body instead of a string message. |
+| `--new-session` | Drop the saved local session and start fresh. |
+| `--port <n>` | Match the port you started `run` with. |
+
+## When to graduate to remote
+
+Local dev validates code shape; remote validates infra + identity + Foundry binding. Move to deploy when:
+
+- You changed `agent.yaml` `model:`, `tools:`, `connections:`, or `protocols:`. Those only take effect on the deployed agent.
+- You need to test against real Foundry connections (search indexes, Bing, MCP, A2A) that have no local mock.
+- You are ready to publish a new immutable agent version.
+
+Next step -> [deploy/deploy.md](../../deploy/deploy.md).
+
+## Common failures
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `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. |
+| `could not detect project type in <dir>` | Missing project marker file | Set `startupCommand` in `azure.yaml` or pass `--start-command`. |
+| `cannot use --local with a named agent` | Named-agent invoke against localhost | Drop the name; only one local agent at a time. |
+| `cannot use --version with --local` | `--version` is remote-only | Drop `--version`, or remove `--local` to hit the deployed agent. |
+| Inspector never opens | Headless env, or extension install failed | Pass `--no-inspector`, or run `azd extension install azure.ai.inspector`. |
+| 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. |