docs: design spec for azd ai connection direct commands by Nathandrake229 · Pull Request #8138 · Azure/azure-dev

Nathandrake229 · 2026-05-11T17:58:00Z

Summary

Adds the design specification for the azure.ai.connection extension and azd ai agent run secret injection.

Spec source: https://github.com/coreai-microsoft/foundrysdk_specs/pull/165

What's in the design spec

New Extension: `azure.ai.connection` (namespace: `ai.connection`)

11 commands: connection CRUD (create, update, delete, show, list) + metadata (set, remove, list) + key (set, remove, list)
Hybrid API architecture: ARM SDK for CRUD + data-plane for credential fetch — validated live
Full 5-level endpoint resolution: flag, azd env, global config, env var, structured error
ARM resource ID discovery: Bootstrap data-plane GET to extract subscription/resource group — enables standalone usage without an azd project
--from-file mutual exclusivity, --force dual semantics, --show-credentials opt-in
Standalone usability: Works outside azd projects with just a project endpoint URL

Agent Run Secrets (`azure.ai.agents` extension)

--secret KEY=VALUE, --secret-from-env KEY, --secret-from-keyvault KEY=vault-url (all repeatable)
Pure local operation — secrets injected as env vars into the spawned agent process

Open Items

8 tracked items including API endpoint confirmation, enum finalization, and a resolution order contradiction in the requirement spec.

Files changed

cli/azd/docs/design/azure-ai-direct-commands.md — New design specification

Add design specification for the azure.ai.connection extension and azd ai agent run secret injection, covering: - New standalone extension (namespace: ai.connection) for connection CRUD - Hybrid API architecture: ARM SDK for CRUD + data-plane for credentials - Full 5-level project endpoint resolution cascade - ARM resource ID discovery via data-plane bootstrap GET - Agent run --secret, --secret-from-env, --secret-from-keyvault flags - Error handling, output formatting, and registry entry Spec source: coreai-microsoft/foundrysdk_specs#165 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- list/show output includes credential reference strings for agent.yaml - azd ai agent run resolves connection credential references at startup - Developer can copy reference strings directly into agent.yaml Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a new design specification document for planned “direct commands” around Foundry connections (azd ai connection / azure.ai.connection extension) and for secret injection enhancements to azd ai agent run in the existing azure.ai.agents extension.

Changes:

Introduces a comprehensive design spec covering command surface, endpoint resolution, and hybrid ARM + data-plane API usage.
Describes proposed flags and behaviors for agent-run secret injection (literal/env/Key Vault) and connection credential reference resolution.
Documents proposed extension structure, error handling approach, and output formatting conventions.

- Fix GET to POST for getConnectionWithCredentials (it is a POST) - Align buildCredentialReferences with ConnectionCredentials struct - Fix resolveConnectionReferences to handle credential types correctly - Add metadata capability to extension.yaml - Use azdClient.Prompt().Confirm() instead of fmt.Scanln for delete - Standardize resolveProjectEndpoint signature to (ctx, cmd) - Fix CRUD commands to use resolveConnectionContext pattern - Add validation to parseKeyValuePairs for malformed input - Align Connection model with actual data-plane response shape Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-05-11T18:27:11Z

📋 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

A few systemic issues need attention before implementation. The Copilot bot's inline comments cover additional internal inconsistencies (POST vs GET, Credentials shape, parseKeyValuePairs error handling) that are all valid.

CI is failing - cspell-lint reports 39 unknown words. See inline comment on line 3.
CRUD commands skip ARM context resolution - Section 4.4 defines resolveConnectionContext as "the shared context that every command uses," but only delete actually calls it. The create, update, show, and list examples call resolveProjectEndpoint + NewARMClient(endpoint, cred) directly, which can't work since NewARMClient needs subscription/rg/account/project (per section 5.8).
Endpoint resolution cascade diverges from azure.ai.agents - The 5-level cascade adds global config and FOUNDRY_PROJECT_ENDPOINT env var steps that the agents extension doesn't have. If this is a deliberate design choice for standalone usability, call it out explicitly. Two extensions in the ai.* namespace resolving endpoints differently will confuse users.
Bootstrap API call on every invocation - discoverARMContext hits the data-plane on every command to extract subscription/rg. Consider caching in azd global config after first resolution. The agents extension uses config_store.go for similar per-endpoint state.
Registry entry format doesn't match actual registry.json - See inline comment on line 1633.

jongio · 2026-05-11T21:24:18Z

+
+### 4.4 Full Connection Context Resolution
+
+Putting it all together — the shared context that every command uses:


[HIGH] Only delete uses resolveConnectionContext - other commands can't work as written

Section 4.4 describes this as "the shared context that every command uses," but the create (line 806), update (line 891), show, and list command examples bypass it entirely. They call resolveProjectEndpoint + NewARMClient(endpoint, cred) directly, which can't work because NewARMClient (defined in section 5.8) requires (subscriptionID, rg, account, project, cred).

All commands that touch the ARM API should use resolveConnectionContext or an equivalent that provides the ARM resource ID components.

Fixed in commit 83b9d63. All five CRUD commands (create, update, delete, show, list) now use resolveConnectionContext(ctx, cmd). No direct NewARMClient calls from command code.

Confirmed - all 5 CRUD commands now route through resolveConnectionContext. Looks correct.

jongio · 2026-05-11T21:24:18Z

+
+After the extension is built and published, add to `cli/azd/extensions/registry.json`:
+
+```json


[MEDIUM] Registry entry format doesn't match actual registry.json

The actual registry.json uses:

A top-level "schemaVersion": "1.0" field

An "extensions" array (not an object keyed by extension ID)

Each entry has an "id" field and a "versions" array (not an object)

Check cli/azd/extensions/registry.json for the actual format.

Fixed in commit 83b9d63. Updated to match actual registry.json format -- schemaVersion at top level, extensions as array, versions as array.

No longer applicable since connections are part of the agents extension now. No separate registry entry needed.

- Remove agent run --secret flags (connections are the secret store) - Add --kind filter caveat (client-side only, needs API confirmation) - Change default output format from json to table - Fix cspell ignore list - Add note on endpoint resolution divergence from existing pattern - Add ARM context caching optimization - Fix all CRUD commands to use resolveConnectionContext - Fix registry.json format to match actual schema Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- ARM supports server-side category filtering (validated: ?category=RemoteTool) - Data-plane ignores filter params (always returns all connections) - ARM PUT is unconditional upsert (silently overwrites existing connections) - create without --force now does a pre-check GET to detect duplicates - Updated ARM client List to use server-side category filter option Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Move from separate extension to inside azure.ai.agents (per John's review) - Follow PR #8100 pattern: namespace ai, sibling subcommand groups - Connection code in internal/connections/ (self-contained, no agent imports) - Clarify connection commands don't modify YAML files - Clarify run.go credential resolution is additive to existing env var handling - Add namespace conflict with other ai.* extensions as open item - Update registry section (no separate entry needed) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jongio

Incremental review covering 3 new commits since my last pass.

Prior findings:

resolveConnectionContext not used by all commands: fixed, all 5 CRUD commands use it now
Registry entry format: no longer applicable (connections embedded in agents extension)
Bootstrap API caching: added
Endpoint resolution divergence: intentional per spec requirement, documented

The restructuring to embed connections inside the agents extension addresses the "not a new extension" feedback well. The internal/connections/ package being self-contained with zero imports from internal/agents/ is a clean separation that supports future extraction if needed.

One concern below about the namespace change that affects the command-tree design in sections 2 and 5.

jongio · 2026-05-16T17:39:08Z

+```yaml
+# yaml-language-server: $schema=../extension.schema.json
+id: azure.ai.agents
+namespace: ai


Changing to namespace: ai will conflict with three existing extensions that use ai.* namespaces:

azure.ai.models (namespace: ai.models)

azure.ai.finetune (namespace: ai.finetuning)

microsoft.azd.ai.builder (namespace: ai.builder)

The framework's namespacesConflict check in cmd/extension_namespace_test.go explicitly tests that ai vs ai.agent is a conflict (lines 31-45). Same logic applies to ai vs ai.models, etc. The routing in cmd/extensions.go mounts namespace: ai as an extension command at the ai node, blocking other extensions from using it as a routing prefix.

John's feedback was "still remain in its own namespace," which reads as keeping ai.agent or ai.connection rather than claiming the ai root.

Two options that don't need framework changes:

Keep namespace: ai.agent and mount connections as sub-commands (azd ai agent connection ...)

Register connections via a thin wrapper extension at ai.connection that imports the shared code from the agents directory (one codebase, two entry points)

Open question #8 flags this, but since it drives the entire command-tree design in sections 2 and 5, it should be resolved before the spec is implementation-ready.

jongio · 2026-05-16T17:39:08Z

+displayName: Foundry AI (Preview)
+description: Manage agents and connections in Microsoft Foundry. (Preview)
+usage: azd ai <command> [options]
+version: 0.1.30-preview


The current agents extension on main is at 0.1.31-preview but the spec shows 0.1.30-preview. Should be updated to match or exceed the current version.

microsoft-github-policy-service Bot assigned Nathandrake229 May 11, 2026

Nathandrake229 marked this pull request as ready for review May 11, 2026 18:11

Copilot AI review requested due to automatic review settings May 11, 2026 18:11

Nathandrake229 requested review from JeffreyCA, hemarina, jongio, rajeshkamal5050, tg-msft, vhvb1989, wbreza and weikanglim as code owners May 11, 2026 18:11

Copilot started reviewing on behalf of Nathandrake229 May 11, 2026 18:13 View session

Nathandrake229 mentioned this pull request May 11, 2026

Add azd ai connection create/update/show/list to manage Foundry Connections #8139

Closed

Nathandrake229 linked an issue May 11, 2026 that may be closed by this pull request

Add azd ai connection create/update/show/list to manage Foundry Connections #8139

Closed

Copilot AI reviewed May 11, 2026

View reviewed changes

jongio reviewed May 11, 2026

View reviewed changes

therealjohn requested changes May 12, 2026

View reviewed changes

Comment thread cli/azd/docs/design/azure-ai-direct-commands.md Outdated

Comment thread cli/azd/docs/design/azure-ai-direct-commands.md Outdated

Comment thread cli/azd/docs/design/azure-ai-direct-commands.md

Comment thread cli/azd/docs/design/azure-ai-direct-commands.md Outdated

Naman Tyagi and others added 2 commits May 12, 2026 11:21

hund030 mentioned this pull request May 13, 2026

doc: design spec for azd ai agent toolbox direct commands #8160

Open

Nathandrake229 mentioned this pull request May 14, 2026

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

Merged

jongio reviewed May 16, 2026

View reviewed changes


		### 4.4 Full Connection Context Resolution

		Putting it all together — the shared context that every command uses:


		After the extension is built and published, add to `cli/azd/extensions/registry.json`:

		```json

Conversation

Nathandrake229 commented May 11, 2026

Summary

What's in the design spec

New Extension: azure.ai.connection (namespace: ai.connection)

Agent Run Secrets (azure.ai.agents extension)

Open Items

Files changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Prioritization Note

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

New Extension: `azure.ai.connection` (namespace: `ai.connection`)

Agent Run Secrets (`azure.ai.agents` extension)

github-actions Bot commented May 11, 2026 •

edited

Loading