feat: add azd ai agent connection commands + credential resolution in run

[Nathandrake229]

Summary

Adds azd ai agent connection commands for managing Foundry project connections, and credential reference resolution in azd ai agent run.

Design spec: #8138
Namespace issue: #8166
PM spec: coreai-microsoft/foundrysdk_specs#165

New Commands

azd ai agent connection list

List all connections in the Foundry project.

Flags:
  --kind string              Filter by connection kind (e.g., RemoteTool, ApiKey)
  -p, --project-endpoint     Foundry project endpoint URL
  -o, --output               Output format: table (default), json

azd ai agent connection show <name>

Show connection details. Metadata only by default.

Flags:
  --show-credentials         Fetch credential values from the data plane
  -p, --project-endpoint     Foundry project endpoint URL
  -o, --output               Output format: table (default), json

When --show-credentials is used, output includes credential reference strings for agent.yaml:

Credential References (for agent.yaml):
  x-api-key: ${{connections.my-conn.credentials.x-api-key}}

azd ai agent connection create <name>

Create a new connection. Fails if connection already exists unless --force is used.

Flags:
  --kind string              Connection kind (e.g., remote-tool, cognitive-search, api-key)
  --target string            Target URL or ARM resource ID
  --auth-type string         Auth type: api-key, custom-keys, none (default: none)
  --key string               API key value (for api-key auth)
  --custom-key stringArray   Custom key=value pair (repeatable, for custom-keys auth)
  --metadata stringArray     Metadata key=value pair (repeatable)
  --force                    Replace existing connection (upsert via ARM PUT)
  -p, --project-endpoint     Foundry project endpoint URL

Examples:

# api-key connection
azd ai agent connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net/ \
  --auth-type api-key --key "abc123"

# custom-keys connection (e.g., MCP tool with API key header)
azd ai agent connection create my-tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys --custom-key "x-api-key=tvly-abc123"

# no-auth connection
azd ai agent connection create my-public \
  --kind remote-tool \
  --target https://public-mcp.example.com \
  --auth-type none

azd ai agent connection update <name>

Update a connection's target or credential values. Only specified flags are changed; all other fields are preserved (GET-then-PUT merge). Does not accept --auth-type (delete and recreate to change auth type).

Flags:
  --target string            New target URL or ARM resource ID
  --key string               New API key value (for api-key auth)
  --custom-key stringArray   Update custom key=value (repeatable, for custom-keys auth)
  -p, --project-endpoint     Foundry project endpoint URL

Examples:

azd ai agent connection update prod-search --key "$NEW_SEARCH_KEY"
azd ai agent connection update my-conn --target https://new-endpoint.com

azd ai agent connection delete <name>

Delete a connection. Prompts for confirmation unless --force is used.

Flags:
  --force                    Skip confirmation prompt
  -p, --project-endpoint     Foundry project endpoint URL

azd ai agent connection metadata set|remove|list

Manage metadata key-value pairs on a connection. Metadata is organizational data attached to connections (e.g., type: custom_MCP, ApiType: Azure).

azd ai agent connection metadata list <connection-name>
azd ai agent connection metadata set <connection-name> <key=value>
azd ai agent connection metadata remove <connection-name> <key>

azd ai agent connection key list

List credential keys on a connection (fetches from data-plane). Shows actual secret values.

azd ai agent connection key list <connection-name>

Agent Run Enhancement

Credential reference resolution in azd ai agent run

When azd ai agent run starts a local agent, it now scans agent.yaml environment_variables for ${{connections.<name>.credentials.<key>}} patterns, resolves them via the Foundry data-plane API, and injects actual credential values into the spawned agent process.

Example agent.yaml:

environment_variables:
  - name: TAVILY_API_KEY
    value: "${{connections.my-conn.credentials.x-api-key}}"

At azd ai agent run time, the extension fetches the credential from the Foundry project and sets TAVILY_API_KEY=<actual-secret> in the agent process.

This is additive — existing env var handling (${VAR} references, FOUNDRY_* translations) is unchanged.

Architecture

• Connection code in internal/connections/ — self-contained, no agent imports, easy to lift-and-shift
• Hybrid API: ARM SDK (armcognitiveservices.ProjectConnectionsClient) for CRUD, data-plane (POST getConnectionWithCredentials) for credential fetch
• ARM PUT requires credentials but ARM GET never returns them — rebuildAndPutConnection helper fetches credentials from data-plane before every PUT (used by update, metadata set, metadata remove)
• ARM context discovery via data-plane bootstrap GET (extracts subscription/rg from connection id field)
• 5-level project endpoint resolution: -p flag > azd env > global config > env var > error
• Commands under azd ai agent connection until core namespace change lands ([Agents Extension] azd ai connection commands — blocked by namespace prefix conflict #8166)

Files changed

New files (connection commands):

• internal/connections/cmd/root.go — connection subcommand group with -p flag
• internal/connections/cmd/endpoint.go — endpoint resolution + ARM discovery
• internal/connections/cmd/context.go — shared connection context (ARM + data-plane clients)
• internal/connections/cmd/connection.go — list, show, create, update, delete + helpers
• internal/connections/cmd/connection_metadata.go — metadata set, remove, list
• internal/connections/cmd/connection_key.go — key set, remove, list
• internal/connections/pkg/connections/models.go — Connection, ConnectionCredentials types
• internal/connections/pkg/connections/data_client.go — data-plane client
• internal/connections/exterrors/errors.go — structured error factories
• internal/connections/exterrors/codes.go — error codes

New files (agent run enhancement):

• internal/cmd/connection_credentials.go — scans manifest for connection refs, resolves via data-plane

Modified files:

• internal/cmd/root.go — adds connection subcommand (one line)
• internal/cmd/run.go — adds credential resolution step after existing env var loading
• go.mod / go.sum — adds armcognitiveservices SDK dependency

[Copilot]

Pull request overview

Adds Foundry project connection management commands to the azure.ai.agents extension and enhances azd ai agent run to resolve ${{connections.<name>.credentials.<key>}} references from agent.yaml at runtime via the Foundry data-plane API.

Changes:

• Introduces azd ai agent connection {list,show,create,delete} command group backed by ARM CRUD + data-plane credential fetch.
• Adds a data-plane client + models and a small structured error helper package for the new connection commands.
• Updates azd ai agent run to scan the agent manifest for connection credential references and inject resolved secrets into the spawned agent process environment.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
cli/azd/extensions/azure.ai.agents/internal/connections/pkg/connections/models.go	Adds connection/credential models and a helper to parse credential payloads.
cli/azd/extensions/azure.ai.agents/internal/connections/pkg/connections/data_client.go	Adds a Foundry data-plane client for listing connections and fetching credentials.
cli/azd/extensions/azure.ai.agents/internal/connections/exterrors/errors.go	Adds helpers to build structured extension errors and map Azure SDK errors.
cli/azd/extensions/azure.ai.agents/internal/connections/exterrors/codes.go	Defines error codes and operation names used by the connections feature.
cli/azd/extensions/azure.ai.agents/internal/connections/cmd/root.go	Wires the connection subcommand group and shared --project-endpoint flag.
cli/azd/extensions/azure.ai.agents/internal/connections/cmd/endpoint.go	Implements project endpoint resolution and ARM context discovery.
cli/azd/extensions/azure.ai.agents/internal/connections/cmd/context.go	Creates shared connection context (ARM + data-plane clients, credential creation).
cli/azd/extensions/azure.ai.agents/internal/connections/cmd/connection.go	Implements list/show/create/delete command handlers and output formatting.
cli/azd/extensions/azure.ai.agents/internal/cmd/connection_credentials.go	Adds agent.yaml scanning + credential reference resolution for run.
cli/azd/extensions/azure.ai.agents/internal/cmd/run.go	Calls connection credential resolution and injects resolved secrets into env.
cli/azd/extensions/azure.ai.agents/internal/cmd/root.go	Registers the new connection command group on the extension root.
cli/azd/extensions/azure.ai.agents/go.mod	Adds ARM SDK dependency needed by the new connection commands.
cli/azd/extensions/azure.ai.agents/go.sum	Updates dependency checksums for the new ARM SDK module.

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

[trangevi]

Please add tests

[trangevi]

/check-enforcer override

[JeffreyCA]

@microsoft-github-policy-service rerun