Feature: Add ai.project command for Foundry Project context management

[huimiu]

Developers working outside an azd project directory (e.g., from a scratch directory or a coding-agent session) need a way to set an active Foundry project endpoint once and have all subsequent azd ai commands pick it up automatically ΓÇö without repeating --project-endpoint on every call.

This is the prerequisite for all other azd ai direct commands (connection, toolbox, skill, routine). The endpoint resolution chain implemented here becomes shared middleware across the entire surface.

---

Commands

azd ai project set <endpoint>

Store the active Foundry project endpoint in global config.

azd ai project set https://<account>.services.ai.azure.com/api/projects/<project>

• Writes to ~/.azd/config.json under extensions.ai-agents.context.endpoint
• Prints a one-line warning when run inside an azd project directory (the active azd env takes precedence over global context in that case)

Config shape:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://<account>.services.ai.azure.com/api/projects/<project>",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

azd ai project unset

Clear the stored endpoint from global config.

azd ai project unset

azd ai show

Display the currently resolved project endpoint and which source provided it.

azd ai show
# Project endpoint:  https://<account>.services.ai.azure.com/api/projects/<project>
# Source:            global config (~/.azd/config.json)

---

Endpoint Resolution Chain (shared middleware)

This must be implemented as middleware used by every azd ai command:

1. -p / --project-endpoint flag (per-command override)
2. Active azd env value (when inside an azd project)
3. Global config (extensions.ai-agents.context.endpoint)
4. FOUNDRY_PROJECT_ENDPOINT environment variable
5. Structured error on stderr if none resolved:

   No Foundry project endpoint resolved. Run 'azd ai project set' to set one, or pass '--project-endpoint'.

---

Cross-cutting Flags

All azd ai commands must support these flags (implement alongside the middleware):

Flag	Behavior
-p / --project-endpoint <url>	Per-command override of resolved endpoint
--output json	Machine-readable JSON output
--no-prompt	Non-interactive mode (CI / coding agents)
--debug	Diagnostic logging to stderr

---

Acceptance Criteria

• azd ai project set <url> writes endpoint to ~/.azd/config.json and prints confirmation
• azd ai project unset clears the endpoint and prints confirmation
• azd ai show displays the resolved endpoint and its source (flag / env var / azd env / global config)
• Running azd ai project set inside an azd project directory shows a warning that azd env takes precedence
• Endpoint resolution chain is implemented as shared middleware used by all azd ai commands
• All three commands support --output json, --no-prompt, --debug
• If no endpoint is resolved, a structured error with actionable suggestion is printed to stderr
• All three commands work standalone (outside an azd project directory)

---

Dependencies

• azd core CLI surface (azd ai namespace, global flags, env resolution, output formatter) ΓÇö Committed (Travis Angevine)
• No external service dependencies ΓÇö pure local state management

Unblocks

All azd ai connection, azd ai toolbox, azd ai skill, and azd ai routine commands depend on this middleware being in place.

Related

• Tech Spec: azure-ai-direct-commands.md
• Part of: azd ai Direct Commands epic