feat: add azd ai agent project commands for Foundry endpoint management

[huimiu]

Summary

Adds azd ai agent project command group to the azure.ai.agents extension, enabling users to persist and resolve a Microsoft Foundry project endpoint without requiring an azd environment or explicit flags on every command.

Changes

• New project command group (project set, project unset, project show): persists the Foundry project endpoint in ~/.azd/config.json under extensions.ai-agents.context.endpoint.
• 5-level endpoint resolution cascade in agent_context.go: resolves from (1) --project-endpoint flag, (2) active azd env AZURE_AI_PROJECT_ENDPOINT, (3) global config, (4) host env var FOUNDRY_PROJECT_ENDPOINT, then (5) structured error with actionable guidance.
• Endpoint validation (project_endpoint.go): validates and normalizes Foundry https://*.services.ai.azure.com URLs; surfaces a non-fatal warning when the path doesn't match /api/projects/<name>.
• Global config persistence (project_context_store.go): read/write helpers for the global config store.
• Docs: added FOUNDRY_PROJECT_ENDPOINT to environment-variables.md.
• Tests: unit tests for validation, resolution cascade, and all three subcommands.

Related

Closes #8124
Design spec: #8152

Test

• Set a project endpoint
• Show the resolved endpoint
• Show as JSON (stable machine-readable output)
• Invalid scheme → should reject with structured error
• Non-Foundry host → should reject
• Clear the stored endpoint

[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.

[Copilot]

Pull request overview

This PR extends the azure.ai.agents azd extension with a new project command group for managing a persisted Microsoft Foundry project endpoint, and upgrades endpoint resolution for agent commands to use a 5-level cascade (flag → azd env → global config → host env var → structured error). It also adds endpoint URL validation/normalization, introduces a new structured error code, and documents the new host environment variable.

Changes:

• Added azd ai agent project {set|unset|show} commands to persist/clear/inspect the Foundry project endpoint in ~/.azd/config.json.
• Implemented a shared 5-level project endpoint resolver and updated agent endpoint resolution to use it.
• Added endpoint validation helpers, unit tests for validation + parts of the resolver, and documented FOUNDRY_PROJECT_ENDPOINT.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cli/azd/extensions/azure.ai.agents/internal/exterrors/codes.go	Adds missing_project_endpoint error code for structured dependency errors.
cli/azd/extensions/azure.ai.agents/internal/cmd/root.go	Wires the new project command group into the extension command tree.
cli/azd/extensions/azure.ai.agents/internal/cmd/project.go	Defines the project parent command and registers set/unset/show subcommands.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_set.go	Implements project set to validate and persist an endpoint (with warnings).
cli/azd/extensions/azure.ai.agents/internal/cmd/project_unset.go	Implements project unset to clear persisted endpoint (idempotent).
cli/azd/extensions/azure.ai.agents/internal/cmd/project_show.go	Implements project show to resolve and print endpoint + source (table/json).
cli/azd/extensions/azure.ai.agents/internal/cmd/project_endpoint.go	Adds endpoint source enum, host suffix validation, normalization, and missing-endpoint error helper.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_context_store.go	Adds global config read/write helpers for persisted endpoint context.
cli/azd/extensions/azure.ai.agents/internal/cmd/agent_endpoint.go	Adds guidance comment about keeping host-suffix validation logic in sync.
cli/azd/extensions/azure.ai.agents/internal/cmd/agent_context.go	Implements the 5-level resolver and routes resolveAgentEndpoint through it.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_unset_test.go	Adds basic command-arg and output-flag configuration tests for unset.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_show_test.go	Adds basic command-arg/flag tests plus helper-function tests for show.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_set_test.go	Adds basic command-arg and output-flag configuration tests for set.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_resolver_test.go	Adds unit tests for resolver flag precedence + host env fallback + error cases.
cli/azd/extensions/azure.ai.agents/internal/cmd/project_endpoint_test.go	Adds unit tests for endpoint validation/normalization and missing-endpoint error typing.
cli/azd/docs/environment-variables.md	Documents FOUNDRY_PROJECT_ENDPOINT as a host-level fallback source.

[jongio]

Clean implementation of the project command group. The 5-level cascade is well-designed, validation is strict at every level (no silent fallthrough on bad values), and the stubbable seams (readAzdHostedSourcesFunc, lookupEnvFunc) make the resolver testable without a running daemon. Tests cover the priority ordering and error cases thoroughly.

[huimiu]

Thanks for the thorough review! Addressed all the feedback in this update:

From @jongio:

• Added a doc comment to containsGRPCCode calling out the single-wrap limitation. Future callers will know it won't traverse errors.Join trees.
• Unified Foundry host validation: parseAgentEndpoint now calls isFoundryHost instead of its own constant, so the two validators can't silently drift anymore when new suffixes are added.

From @trangevi:

• Refactored project set, project show, and project unset to follow the action object pattern (ProjectSetAction.Run, etc.), for a clean separation between "prepare" and "do the work".
• Removed the --project-endpoint flag from project show. You're right that it adds no real value. The command now always shows the fully resolved endpoint from the cascade.
• Replaced the lookupEnvFunc seam and stubLookupEnv helper with plain t.Setenv. Agreed, mocking os.Getenv at the package level was overkill.
• Renamed the config path from .context to .project.context so it is clearly scoped and leaves room for future per-agent context without collision.

[trangevi]

/check-enforcer override

The build is showing complete, status is just not being reported

[JeffreyCA]

Approving for cli/azd/docs/environment-variables.md change, looks good!