docs: add design spec for RemoteA2A connection support and catalog in connections command

[Nathandrake229]

…tegration

Covers two follow-up requests on PR #8174:

1. RemoteA2A/WorkIQ connection support (A2A protocol tools)
2. Asset Catalog API integration for --from-catalog picker

Key findings:

• RemoteA2A is already an ARM-registered ConnectionCategory
• CustomKeys and None auth types already work, OAuth2 blocked on SDK
• normalizeKind alias required for list --kind filtering (case-sensitive)

[Copilot]

Pull request overview

Adds a new design spec documenting proposed follow-up work for the azd ai agent connection feature set: (1) RemoteA2A/WorkIQ connection support and (2) Asset Catalog-backed connection creation via a --from-catalog picker. This lives under cli/azd/docs/design/ alongside other azd design documents.

Changes:

• Document RemoteA2A connection category behavior, constraints, and a proposed remote-a2a kind alias for filtering.
• Document an Asset Catalog integration proposal (--from-catalog) including UX sketch, API field mapping, and rollout phases.
• Add testing plan and open questions for the above follow-up work.

[github-actions]

🔗 Linked Issue Required

Thanks for the contribution! Please link a GitHub issue to this PR by adding Fixes #123 to the description or using the sidebar.
No issue yet? Feel free to create one!

[lindazqli]

nit: it wont be translated into remoteTool connection and doesn't use server_label

[lindazqli]

it supports the same auth types as remoteTool: no auth, custom keys, oauth2, userentratoken, agenticidentity, etc

[lindazqli]

what is needed to add this?

[lindazqli]

is this impacting both remoteTool and remoteA2A connection?

[lindazqli]

there are two registries we want to support this one and the connector registry

[lindazqli]

im ok with this - these are local mcp servers customers need to host

[lindazqli]

there is some logic UX has implemented to tell the auth type, i can share that

[lindazqli]

expected

[wbreza]

Review Summary

Solid, well-researched design spec. Technical claims verified accurate against the existing codebase (RemoteA2A is ARM-registered, CustomKeys/None auth already work, OAuth2 SDK gap is real, and the normalizeKind() alias requirement is correct). Structure follows existing cli/azd/docs/design/ conventions and the PR description aligns with the doc content. Ready for implementation once the readability issue below is addressed.

---

🟠 High — Mojibake throughout the document

The file contains genuinely corrupted multi-byte sequences (not a display artifact). Byte-level inspection confirms CE 93 C3 87 C3 B6 ("ΓÇö") where UTF-8 em-dash (E2 80 94, "—") belongs — the classic UTF-8-misinterpreted-as-cp1252-then-re-encoded pattern.

Affects the title (line 1) and dozens of lines throughout — tables, tree diagrams, bullets, checkmark columns.

Suggested fix: Re-save the file as UTF-8 from a clean source, or run a find/replace pass:

Mojibake	Should be
ΓÇö	— (em-dash)
ΓåÆ	→ (right arrow)
Γ£à	✅
Γ¥î	❌
Γö£ΓöÇΓöÇ	├──
ΓööΓöÇΓöÇ	└──

🟡 Medium — remote-a2a alias framing is ambiguous

Section 2.4 / Phase 1 reads as if the normalizeKind() alias for remote-a2a already exists or just needs to be documented. It's actually a new mapping entry being proposed. Consider stating explicitly: "Add a new mapping entry "remote-a2a": "RemoteA2A" (does not currently exist in the map)."

🟡 Medium — Use full file paths to disambiguate extension vs. core

The doc uses shorthand like internal/connections/cmd/connection.go without making it clear this lives in the cli/azd/extensions/azure.ai.agents/ extension, not core azd. A reader new to the codebase could easily look in the wrong place. Recommend full paths, e.g., cli/azd/extensions/azure.ai.agents/internal/connections/cmd/connection.go:normalizeKind().

🟢 Nits (non-blocking)

• A few long lines and table cells wrap awkwardly — minor readability nit.
• Linda's quoted requirements in Section 3.2 would benefit from an inline link to the PR #8174 thread for traceability.

---

What's good

• Technical accuracy verified against actual code (ConnectionCategory registration, auth-type handling, OAuth2 SDK gap, case-sensitive --kind matching).
• Follows existing cli/azd/docs/design/ doc conventions (Background → Requirements → Implementation → Testing → Open Questions → Phased rollout).
• Clear phase breakdown makes downstream PR scoping straightforward.
• PR description fully aligned with doc contents.

[wbreza]

Re-Review (3 new commits since prior review)

Scope has expanded from docs-only to docs + implementation code (connection.go +62/-3). Flagging items that are either new since my prior review or remain unresolved.

Status of prior findings

Prior finding	Status
🟠 Mojibake (ΓÇö, ΓåÆ, Γ£à, Γö£ΓöÇΓöÇ)	Not fixed — byte-level check still shows CE 93 C3 87 C3 B6 where UTF-8 E2 80 94 (—) belongs
🟡 remote-a2a alias framing	Addressed
🟡 Full file paths	Partially — now "extension's connection.go" but still no full path
🟢 Long lines / #8174 link	Partially — link present; ~48 lines still >100 chars

---

🔴 Blocking

1. Mojibake still throughout the design doc
Three commits later, the encoding hasn't been touched. Recommend re-saving the file from a UTF-8-clean source (or find/replace pass):

Mojibake	Should be
ΓÇö	—
ΓåÆ	→
Γ£à	✅
Γ¥î	❌
Γö£ΓöÇΓöÇ	├──
ΓööΓöÇΓöÇ	└──

2. files/pr-8174-review-fixes-findings.md looks accidentally committed
This file is at repo root in a non-standard files/ directory and its content documents review fixes for a different PR (#8174). It does not belong in this PR. Suggest removing it.

🟠 High

3. Title/description no longer reflects scope
The PR is no longer docs-only — it now ships OAuth2 flag validation and a remote-a2a alias in connection.go. Consider:

• Renaming title from docs: → feat: (or split impl into a sibling PR).
• Adding a "what this changes in code" section to the description so reviewers and the changelog catch it.

4. No tests for the new code paths
connection_test.go is untouched, but connection.go adds:

• New --client-id / --client-secret flag wiring.
• A new validation branch (if a.flags.authType == "oauth2") requiring both flags.
• A new "remote-a2a": "RemoteA2A" entry in normalizeKind().

Each of these is a new behavioral branch that should have a unit test in connection_test.go per the extension's testing conventions (see cli/azd/extensions/azure.ai.agents/AGENTS.md).

5. Asset Catalog API method inconsistency (design doc ~line 335)
Doc shows POST https://api.catalog.azureml.ms/asset-gallery/v1.0/tools, but the surrounding "Tested Findings" describes a list/read operation. Looks like it should be GET (or please clarify what's being created if POST is intentional). Also flagged by copilot-pull-request-reviewer and unresolved.

6. Non-existent yacflow/tests/fixtures/ path (design doc ~line 54)
There is no yacflow/ directory in this repo. Either link to the actual location (different repo?) or remove the citation. Also flagged by copilot-pull-request-reviewer.

🟡 Medium

7. OAuth2 flags silently ignored for non-oauth2 auth types
--client-id / --client-secret are accepted as global flags but only validated when --auth-type oauth2. If a user passes them with another auth type they're discarded with no warning. Consider mirroring the existing OAuth2-only guard so misuse fails loudly.

8. File path disambiguation still incomplete (design doc)
The doc still references connection.go without the full cli/azd/extensions/azure.ai.agents/internal/connections/cmd/connection.go prefix. A reader new to the repo can't navigate directly.

9. Hard-coded source line numbers in the design doc
Per copilot-pull-request-reviewer: line-number references (e.g., "line 773–782") drift quickly. Reference function or map names instead.

🟢 Nits

• ~48 lines still exceed 100 chars; minor readability nit.
• Once OAuth2 auth type lands, consider noting it in docs/reference/feature-status.md so the supported auth-type matrix stays current.

---

Code-side spot-check (cli/azd/extensions/azure.ai.agents/internal/connections/cmd/connection.go)

What looks good:

• OAuth2 validation logic is clean and uses an actionable error.
• remote-a2a alias matches the design and addresses the case-sensitivity issue called out in the doc.
• Flag registration uses modern Go patterns.

What needs follow-up: items 4 (tests) and 7 (silent flag ignoring) above.

[wbreza]

Follow-up — cleanup commit 21c93a74 verified

Nice cleanup pass. Confirming what's resolved and what remains.

✅ Resolved

• POC code in connection.go reverted — PR is docs-only again, title now matches scope
• files/pr-8174-review-fixes-findings.md removed
• yacflow path clarified as vienna repo path
• Catalog API method clarified: POST with filter body
• Full file paths now used for connection.go and foundry_projects_client.go

🔴 Still blocking — mojibake encoding

The markdown file's UTF-8 is still corrupted. Byte-level check on the current branch HEAD:

• 109 occurrences of the mojibake byte signature CE 93 C3 … (the Γ… garbage sequences)
• 0 occurrences of proper UTF-8 em-dash E2 80 94 (—)
• The very first line (the doc title) still contains CE 93 C3 87 C3 B6 where E2 80 94 should be

This means on github.com, readers see literal ΓÇö, →, ✅, Γö£ΓöÇΓöÇ in the title, section headers, tables, and tree diagrams. None of the 5 commits have touched the file's encoding.

Suggested one-shot fix: open the file in VS Code (or any editor with UTF-8 support), do a find/replace pass on the 6 patterns below, save as UTF-8 without BOM:

Mojibake	Replace with
ΓÇö	—
ΓåÆ	→
Γ£à	✅
Γ¥î	❌
Γö£ΓöÇΓöÇ	├──
ΓööΓöÇΓöÇ	└──

Once that lands, this should be good to go from a doc-review standpoint.

[wbreza]

Code Review — Supplementing Prior Reviews

Reviewed the latest commit (21c93a7) against prior reviewer feedback and repo design-doc conventions. Posting as a non-blocking comment.

Prior reviewer findings — verification

#	Prior finding	Status
1	UTF-8 mojibake (~109 instances)	❌ Not resolved — ~198 instances now in file (ΓÇö, Γö£ΓöÇΓöÇ, ΓåÆ, Γ£à, Γ¥î)
2	Accidentally-committed iles/pr-8174-review-fixes-findings.md	✅ Resolved
3	Title/description scope drift	✅ Effectively resolved — POC code reverted; PR is genuinely docs-only
4	No tests for new code paths	N/A — POC code reverted
5	Asset Catalog API POST/GET inconsistency	✅ Resolved
6	Non-existent yacflow/tests/fixtures/ path	⚠️ Partially — now scoped to "vienna" repo but still references an external repo
7	OAuth2 flags silently ignored	❌ Doc notes "deferred pending SDK"; no behavioral clarification
8	File path disambiguation	⚠️ Partial — a few paths still ambiguous
9	Hard-coded line numbers	✅ Resolved

---

New findings

🛑 Blocking

N1. Mojibake is the root cause of the cspell-lint CI failure. The ~198 corrupted byte sequences (ΓÇö em-dash, Γö£ΓöÇΓöÇ box-drawing, ΓåÆ arrow, Γ£à/Γ¥î check/cross) are unrecognized tokens to cspell. Re-saving the file as UTF-8 (no BOM) and replacing with proper Unicode —, →, ✅, ❌ (or ASCII equivalents) should clear both the encoding issue and the cspell failure in one pass. Reinforces wbreza's still-unresolved finding #1.

N2. No linked issue → PR Governance check failing. Add Fixes #NNNN (or Relates to #NNNN) to the PR body referencing a tracking issue. The body already mentions PR #8174 but in plain text only.

⚠️ High

N3. Design-doc convention divergence. Existing design specs in this repo (cli/azd/docs/design/azd-update.md, �xtension-flag-architecture.md) use this header pattern:

# Design: <Title>

**Epic**: [#NNNN](link)
**Status**: <Draft | In Progress | Final>
**Decisions**: <link or TBD>

---

This doc uses # Design Spec: plus Author: / Date: / PR Context: / Stakeholder: with no --- separator. Aligning will keep design specs uniform and easier to scan.

N4. PR #8174 references are plain text. Convert PR #8174 mentions to proper markdown links (e.g., #8174) so readers can navigate.

🟡 Medium

N5. OAuth2 deferral is under-specified. The doc says OAuth2 is "deferred pending SDK update" but doesn't define current runtime behavior — does --auth oauth2 silently no-op, emit a validation error, or warn? Spell out the interim contract.

N6. Missing "Assumptions" / "Out of Scope" section. Most existing design specs include explicit Assumptions or Goals/Non-Goals. Adding one would clarify external dependencies (ARM registration assumed, Catalog API availability, SDK OAuth2 timeline).

💡 Low / Nit

N7. Wrap API endpoints in backticks for consistency with the rest of the doc's code styling — e.g., POST https://api.catalog.azureml.ms/asset-gallery/v1.0/tools.

N8. cspell dictionary additions. After mojibake is fixed, terms like RemoteA2A, WorkIQ, yacflow, �zureml, calmforest will likely need to be added as file-scoped overrides in .vscode/cspell.misc.yaml.

---

TL;DR

The two CI blockers (cspell-lint and PR Governance) both have straightforward fixes:

1. Re-save the design doc as UTF-8 (no BOM), replacing mojibake with proper Unicode/ASCII characters
2. Add a Fixes #NNNN linked issue reference to the PR body

The design-doc format alignment (N3) is worth doing while you're in there.

[jongio]

The encoding issue (mojibake) and linked issue requirement are well-covered by prior reviews and are clearly blocking. Adding a few design-level observations that haven't been raised yet:

Duplicate section numbering - There are two sections numbered 3.7 (lines 171 and 187 in the diff). One covers Connector Registry = Asset Catalog, the other covers Proposed Auth Type Changes. Renumber to avoid confusion.

Raw REST bypass needs a sunset plan - Phase 2 proposes raw REST calls for 3 auth types that lack SDK structs. This is pragmatic short-term, but the doc should note when to migrate back to the SDK (e.g., when azure-sdk-for-go adds typed structs for these auth types, replace the raw REST paths). Without that, the bypass becomes permanent technical debt that diverges from how the rest of the connection code works.

Secret handling for OAuth2 flags - The doc proposes --client-secret as a CLI flag but doesn't discuss how the secret is protected. Shell history captures flag values. Consider noting whether --client-secret should accept stdin/env-var input (matching patterns like az login --password reading from stdin) or if the interactive flow prompts without echoing.

Open questions need owners/dates - Section 8 lists 7 open questions but none have target resolution dates or owners beyond @lindazqli to share for item 1. For a design spec headed toward implementation, each question should have an owner and a needed by phase so they don't block downstream work silently.

[jongio]

My prior findings (duplicate section 3.7 numbering, raw REST sunset plan, secret handling for OAuth2 flags, open question ownership) are advisory. The spec is well-researched with validated POC results and a clear phased plan. Approving.

[jongio]

Re-reviewed against the current HEAD (21c93a7). The design holds up: the auth-type inventory is backed by POC results against a live workspace, the ARM-accepted vs SDK-available split is documented clearly, and the phased plan (OAuth2 first, raw REST for the SDK-missing types, catalog picker later) is reasonable.

My earlier comments stay advisory, not blocking. The one concrete item still worth a quick fix is the duplicate 3.7 heading: two sections share the number 3.7 (Connector Registry = Asset Catalog and Proposed Auth Type Changes). Renumber one. The raw REST sunset note, --client-secret handling, and owners/dates on the open questions are optional follow-ups.

Approving.

_{🤖 agent jongio}

[jongio]

Re-reviewed at head 21c93a7. No changes since my prior review, re-affirming approval of the design spec.

[jongio]

Re-reviewed at head 21c93a7. The code this spec proposes has since shipped on main, so several references in the doc are now stale. None of this blocks landing it as a design record, but as written it will send readers to paths and commands that no longer exist.

Worth fixing:

• normalizeKind() moved. It's now in cli/azd/extensions/azure.ai.connections/internal/cmd/connection.go, not under azure.ai.agents (section 4.1).
• The command is azd ai connection, not azd ai agent connection. The connections code was split into its own extension with namespace: ai.connection (sections 1, 4.3, 5.1, 5.4).
• Phase 1 and Phase 2 are done. remote-a2a, oauth2, user-entra-token, project-managed-identity and agentic-identity all ship today, along with --audience, --client-id/--client-secret, --connector-name and the raw REST helper. --from-catalog is the only item still open (section 6).
• cspell-lint is red on this file with 22 unknown words, and has been since the first push.

Minor:

• Two sections are still numbered 3.7. I flagged this in my earlier review and it's unchanged.
• Section 4.4 and section 4.2 disagree on whether a new ConnectionCategory needs a CLI change.

My earlier approval stands. These are accuracy fixes, not objections to the design.

[jongio]

cspell-lint has been failing on this file since the first push, which is part of why the PR is stuck. All 22 unknown words come from this doc:

Naman, Tyagi, yacflow, ahelloworld, apikey, bugbash, northcentralus, workiq, Tavily, tavily, stripeoauth, githuboauth, clientid, clientsecret, lindazqli

Add the technical ones to cli/azd/.vscode/cspell-azd-dictionary.txt and lindazqli to .vscode/cspell-github-user-aliases.txt. That clears the check.

[jongio]

The command is azd ai connection now, not azd ai agent connection. The connections code was pulled out of the agents extension into cli/azd/extensions/azure.ai.connections, whose manifest declares namespace: ai.connection and usage: azd ai connection <command> [options].

This shows up in four places: this tree, the UX examples in 4.3, the quoted question in 5.1, and the picker examples in 5.4.

[jongio]

Still two sections numbered 3.7: this one and Connector Registry = Asset Catalog directly above. Renumber this one to 3.8 and shift the rest.

[jongio]

normalizeKind() isn't at this path anymore. It's in cli/azd/extensions/azure.ai.connections/internal/cmd/connection.go. Under azure.ai.agents/internal/connections/ only pkg is left, the cmd tree moved to the new extension.

The alias itself already landed, so this section is describing work that's done rather than proposed.

[jongio]

This row says a new ConnectionCategory needs no CLI change because --kind passes through, but 4.2 argues the opposite: without an alias, list --kind does a case-sensitive compare and silently drops those connections.

Both hold, just for different inputs. normalizeKind() returns the input unchanged when there's no mapping entry, so a new category works only if the user types the exact ARM PascalCase name. Kebab-case still needs an alias. A one-line caveat here would stop the two sections reading as contradictory.

[jongio]

This phasing is out of date. Both Phase 1 items and all three Phase 2 auth types are on main today:

• remote-a2a is in the normalizeKind() map
• oauth2, user-entra-token, project-managed-identity and agentic-identity are handled in create, with agentic-identity normalized to AgenticIdentityToken
• --audience, --client-id, --client-secret and --connector-name all exist
• the raw REST path lives in raw_connection.go

--from-catalog is the only item still unimplemented.

Open question 4 got answered by the implementation too: OAuth2 needed more than a client id and secret. The shipped flags add --authorization-url, --token-url, --refresh-url and --scopes.

If this is landing as a historical design record, a short status note at the top would stop readers chasing work that's already merged.

[jongio]

Re-approving. My comment review a few minutes ago replaced my earlier approval in GitHub's reviewer state, so the PR was showing no active approvals.

The doc accuracy notes I left still apply but don't block landing this as a design record. cspell-lint is the actual merge blocker: it needs the 22 unknown words added to the azd dictionary.

[jongio]

Re-reviewed at head 21c93a7. Nothing's changed since my last pass, so my approval stands. My inline notes on doc accuracy are still open but they don't block landing this as a design record.

Both red checks are the real blockers, and neither needs a design change.

cspell-lint fails with 22 unknown words, all from this file. cli/azd/AGENTS.md says terms specific to one file belong in a file-scoped overrides entry rather than the global words list, so this goes in cli/azd/.vscode/cspell.yaml under overrides:

  - filename: docs/design/azd-connection-remotea2a-catalog.md
    words:
      - ahelloworld
      - apikey
      - bugbash
      - clientid
      - clientsecret
      - githuboauth
      - lindazqli
      - naman
      - northcentralus
      - stripeoauth
      - tavily
      - tyagi
      - workiq
      - yacflow

PR Governance fails with "PR must be linked to a GitHub issue." That check reads closingIssuesReferences, so it wants either a closing keyword in the description (Fixes #123) or a sidebar link. For a design record you probably don't want a merge to auto-close anything, and the check also honors the skip-governance label, which looks like the cleaner fit here.

--from-catalog is the only piece of this spec that hasn't shipped yet, so if you'd rather link an issue than skip the check, that's the one to file.