doc: design spec for azd ai project context commands and endpoint resolution

[huimiu]

Summary

This PR adds the design spec for the azd ai project set | unset | show commands and the shared 5-level endpoint resolution chain. This is for design review only and contains no implementation code.

What's in this spec

• Three new project subcommands that manage a workspace-level Foundry project endpoint in azd global config (~/.azd/config.json):

  • project set <endpoint>: save an active Foundry project endpoint.
  • project unset: clear the saved endpoint.
  • project show: display the currently resolved endpoint and where it comes from.

• 5-level endpoint resolution cascade:

  1. -p / --project-endpoint flag
  2. Active azd env value (AZURE_AI_PROJECT_ENDPOINT)
  3. Global config (extensions.ai-agents.context.endpoint)
  4. Environment variable FOUNDRY_PROJECT_ENDPOINT
  5. Structured error with actionable suggestion

• Impact on existing azd ai agent commands: The existing 2-level resolver (resolveAgentEndpoint) is expanded to use the new 5-level chain. This is purely additive, meaning every input that worked before still produces the same result. After this change, agent commands also work when only global config or FOUNDRY_PROJECT_ENDPOINT is set.

• Extension placement: The project subtree lives inside the existing azure.ai.agents extension in separate files, so it can be moved into a future azure.ai.project extension without rewrite.

Key design decisions for review

1. Surface form (Open Question 1): azd ai agent project ... (v1, no new extension) vs. azd ai project ... (requires new extension or core passthrough).
2. Endpoint validation: Must be https://, hostname must end with .services.ai.azure.com, path shape triggers a warning but not a hard failure.
3. Back-compat: Existing commands, flags, and config paths are unchanged. Error messages are upgraded to structured errors with suggestions.
4. No secrets: The endpoint URL is not a credential, so no sensitive data is stored.

Related

• Feature spec: azd ai Direct Commands (CLI Surface for Foundry)
• Tracking issue: #8124

[Copilot]

Pull request overview

Adds a design spec documenting the proposed azd ai project (v1: azd ai agent project) context commands (set|unset|show) and a shared 5-level project-endpoint resolution chain intended to be reused across azd ai commands.

Changes:

• Introduces a new design document describing command UX, config storage shape, endpoint validation rules, and structured error behavior.
• Defines a 5-level endpoint resolution cascade (flag → azd env → global config → host env var → structured error).
• Documents intended back-compat impact on existing azd ai agent commands by widening endpoint resolution.

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Review may take a bit longer — reach out to @rajeshkamal5050 or @kristenwomack if you'd like to discuss prioritization.

[jongio]

Solid design doc. The 5-level cascade is clean and the back-compat table in section 8 makes it easy to verify no regressions. A few things to sort out:

Section 8 lists azd ai agent session as a command that uses the resolver, but the extension doesn't have a standalone session command. Session handling lives inside monitor.go and helpers.go. The actual commands calling resolveAgentEndpoint are show, invoke, files, and monitor (via newAgentContext). Fix the list before implementation starts.

I agree with the existing Copilot review on three points: (1) the error suggestion in 4.3 mentioning --project-endpoint won't work for existing agent commands that don't have that flag - the error text should branch or use a universal suggestion, (2) the JSON source field uses two different representations between set and show - pick the enum + sourceDetail approach from show for both, and (3) the config example needs to be valid JSON, not JSONC with trailing commas.

Two additional items: FOUNDRY_PROJECT_ENDPOINT is brand new (doesn't exist in the codebase today) and should be documented in cli/azd/docs/environment-variables.md during implementation. And the hostname suffix .services.ai.azure.com in section 4.2 should be verified against the foundry.azure.com hostnames shown in issue #8124 - if both are valid Foundry host shapes, the validator needs to accept both.

[jongio]

The existing buildAgentEndpoint in agent_context.go constructs https://%s.services.ai.azure.com/api/projects/%s, which matches this suffix. But issue #8124 uses foundry.azure.com as the hostname. Are both valid Foundry hostname shapes? If so, the validator should accept both suffixes.

[huimiu]

foundry.azure.com isn’t a valid host name, sorry for the mix-up. I’ve updated issue #8124

[jongio]

Back-compat is preserved, but there's a new failure mode worth calling out: stale global config. User runs project set for project A, switches to project B, forgets to update. All commands now silently resolve to the wrong endpoint. Consider whether project show should display setAt in table output (not just JSON) as a staleness hint, or whether the resolver should warn when setAt is older than some threshold (e.g., 30 days). Even just documenting project show as the intended debugging tool for this scenario would help.

[huimiu]

Thanks, will surface setAt in project show's table output as a staleness hint and document project show as the debugging tool for stale global config

For the 30-day auto-warning, added a note to revisit based on real user feedback.

[jongio]

Addresses my previous feedback cleanly. The session/sessions fix, centralized suffix list note, explicit env-var documentation requirement, and stale-context diagnostics section all look good. No new issues in the incremental diff.