[Zhijie Huang (hund030)]

Summary

Fixes #10621. Referencing toolboxes on a Copilot-harness prompt agent was silently ignored during deployment, while the legacy singular toolbox field attached an unauthenticated MCP URL that failed at runtime with HTTP 401. This change retires singular toolbox and wires every toolboxes entry to an authenticated UserEntraToken project connection and MCP tool attachment.

Changes

• schemas/azure.ai.agent.json & internal/pkg/agents/agent_yaml: Retire singular toolbox in favor of plural toolboxes ([]ToolboxReference) and reject singular or mixed toolbox/toolboxes configurations with migration guidance.
• internal/project/prompt_skills.go & prompt_graph.go: Validate each toolboxes service dependency in promptGraph, parse the deployed toolbox name and version from TOOLBOX_<NAME>_MCP_ENDPOINT, create or reuse a compatible <toolboxName>-mcp RemoteTool (UserEntraToken, audience: https://ai.azure.com) connection via ARM, and link project_connection_id on each injected MCP tool.
• internal/cmd/agent_dependency_plan.go & resource_services.go: Align init and file-backed dependency planning exclusively with plural toolboxes.

Manual Validation

• Deployed a Copilot-harness prompt agent (harness.type: microsoft_copilot_preview) with one and two azure.ai.toolbox services (web_search) via azd deploy --all --no-prompt in westus2; confirmed via azd ai agent show --output json and ARM GET that <toolbox>-mcp UserEntraToken connections were created/reused and linked via project_connection_id on each MCP tool.
• Invoked the deployed agent via azd ai agent invoke with built-in Copilot tools disabled (microsoft_copilot_toolset_preview defaultConfig.enabled: false) and confirmed live MCP tool calls succeeded against both attached toolboxes without HTTP 401.
• Verified azd deploy rejects singular toolbox, mixed toolbox + toolboxes, and missing uses entries with actionable error messages.

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
24 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

Connection lifecycle, identity resolution, and request replay defects can disrupt existing agents or prevent deployment.

5 open issues

• Reconcile existing toolbox attachments instead of duplicating labels · New
• Preserve existing connections when retargeting toolbox versions · New
• Use replayable request bodies for ARM retries · New
• Resolve account identity from ARM resource ID, not hostname · New
• Guard ownership using resolved resource names and propagate errors · New

What changed in this PR

Addresses #10621 by wiring plural toolboxes references into authenticated MCP attachments for Copilot-harness prompt agents.

Changes:

• Retires singular toolbox with migration diagnostics.
• Resolves deployed toolbox endpoints and creates or reuses authenticated project connections.
• Updates dependency planning, documentation, and tests.

Paths are relative to cli/azd/extensions/azure.ai.agents/.

File	Description
schemas/​azure.ai.agent.json	Rejects legacy and unsupported toolbox configurations.
README.md	Documents plural toolbox references.
internal/​project/​service_target_agent.go	Removes singular dependency wiring.
internal/​project/​prompt_skills.go	Resolves toolbox attachments and authenticated connections.
internal/​project/​prompt_skills_test.go	Tests connections and multiple attachments.
internal/​project/​prompt_json_schema_test.go	Tests plural schema acceptance.
internal/​project/​prompt_inline_test.go	Tests parsing, validation, and round trips.
internal/​project/​prompt_graph.go	Wires plural references into deployment.
internal/​project/​prompt_connections_test.go	Separates toolbox and connection dependencies.
internal/​project/​foundry_dependencies_test.go	Removes obsolete singular-helper coverage.
internal/​project/​agent_definition.go	Rejects legacy and unsupported fields.
internal/​project/​agent_definition_test.go	Updates hosted-agent round-trip coverage.
internal/​pkg/​agents/​agent_yaml/​yaml.go	Defines and decodes plural references.
internal/​pkg/​agents/​agent_yaml/​prompt_strict_inline.go	Adds singular-field migration errors.
internal/​pkg/​agents/​agent_yaml/​prompt_schema_test.go	Tests plural YAML round trips.
internal/​pkg/​agents/​agent_yaml/​parse.go	Validates legacy and voice-agent restrictions.
internal/​exterrors/​codes.go	Adds toolbox connection operation attribution.
internal/​cmd/​resource_services.go	Collects plural toolbox dependencies.
internal/​cmd/​resource_services_test.go	Updates dependency wiring tests.
internal/​cmd/​agent_dependency_plan.go	Removes singular dependency planning.
internal/​cmd/​agent_dependency_plan_test.go	Tests plural planning and legacy rejection.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Endpoint trust validation and attachment collisions remain unresolved.

2 open issues

• Distinct toolbox endpoints collide and overwrite attachments · New
• Unvalidated MCP hosts can receive caller Azure AI tokens · New

5 resolved since last review

• Guard ownership using resolved resource names and propagate errors
• Resolve account identity from ARM resource ID, not hostname
• Use replayable request bodies for ARM retries
• Preserve existing connections when retargeting toolbox versions
• Reconcile existing toolbox attachments instead of duplicating labels

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Connection creation and MCP reconciliation still have correctness issues that can break deployed attachments.

1 open issue

• Exact URL reuse overwrites user-authored server labels · New

1 previously missed issue

In code that hasn't changed since last review

Concurrent deployments race on shared toolbox connection names

cli/​azd/​extensions/​azure.ai.agents/​internal/​project/​prompt_skills.go:995

Parallel agent deployments attaching different versions of the same toolbox can both GET 404 for <toolbox>-mcp, then PUT different targets here. Both return that connection name, so the last PUT leaves one agent's server_url mismatched with its connection target. The version-scoped fallback never runs in this interleaving; services without mutual uses edges deploy in parallel (cli/azd/docs/concurrency-model.md:111–116). Use deterministic endpoint-specific names for new connections, or supported atomic create-if-absent behavior with compatibility checking on conflicts. Add coverage for concurrent first deployments.

2 resolved since last review

• Unvalidated MCP hosts can receive caller Azure AI tokens
• Distinct toolbox endpoints collide and overwrite attachments

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Concurrent connection creation can overwrite another toolbox version’s target, leaving an agent with a mismatched authentication connection.

1 open issue

• Prevent concurrent deployments from overwriting connection targets · New

1 resolved since last review

• Preserved aliases can collide with generated toolbox labels

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Unresolved deployment defects and caller-token connection lifecycle changes require fixes and final human review.

1 open issue

• Prevent MCP connection name collisions across toolboxes · New

1 previously missed issue

In code that hasn't changed since last review

Resolve shared-endpoint MCP placeholders by unclaimed service label

cli/​azd/​extensions/​azure.ai.agents/​internal/​project/​prompt_skills.go:336

When two toolbox services reuse the same endpoint and each has a named MCP placeholder (tools-a and tools-b), the second resolution reuses the already-claimed first entry by URL and returns. The tools-b entry remains without server_url or project_connection_id and is forwarded unchanged to Foundry. Prefer an unclaimed service-label match before URL deduplication so both authored entries retain their options and receive valid attachments. Keep URL reuse as the fallback when no such entry exists, and add a shared-endpoint regression test.

1 resolved since last review

• Prevent concurrent deployments from overwriting connection targets

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Same-named version-1 toolboxes from different Foundry projects still collide on the generated connection name, preventing all references from attaching.

1 open issue

• Add endpoint-scoped names for version-1 connections · New

1 resolved since last review

• Prevent MCP connection name collisions across toolboxes

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Authentication-sensitive resource creation and reconciliation need final human review, with unresolved correctness and migration-diagnostic issues.

1 open issue

• Bound connection names to ARM's 33-character limit · New

1 previously missed issue

In code that hasn't changed since last review

Preserve toolbox migration guidance before schema validation

cli/​azd/​extensions/​azure.ai.agents/​schemas/​azure.ai.agent.json:113

File-backed definitions lose the migration guidance here. LoadAgentDefinitionFile runs schema validation at agent_definition_file.go:137 before content validation at line 151. Singular or mixed input therefore fails this not rule and receives the generic schema diagnostic, without the instruction to use toolboxes. Check the legacy keys before schema validation, retain schema rejection, and assert the migration text in TestLoadAgentDefinitionFileRejectsSingularToolbox.

1 resolved since last review

• Add endpoint-scoped names for version-1 connections

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Authenticated ARM resource creation and the breaking authoring migration warrant human review, with unresolved target-identity and reconciliation defects requiring correction.

1 open issue

• Validate full project identity across accounts · New

1 previously missed issue

In code that hasn't changed since last review

Prefer exact URL matching over label matching

cli/​azd/​extensions/​azure.ai.agents/​internal/​project/​prompt_skills.go:322

An earlier label match can reject a valid exact-URL attachment later in managed.Tools. For example, a direct MCP tool labeled research-tools points to an external URL, while another tool labeled search already points to the deployed toolbox URL. This loop errors on the first entry instead of authenticating search; reversing the entries succeeds with both distinct labels intact. Prefer an exact-URL match before falling back to label matching. Add coverage for both orderings to preserve existing direct tools, aliases, and approval settings.

1 resolved since last review

• Bound connection names to ARM's 33-character limit

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Shared-endpoint references can leave authored MCP placeholders unresolved and submit incomplete tools.

1 open issue

• Resolve service-key placeholders before endpoint deduplication · New

1 resolved since last review

• Validate full project identity across accounts

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Caller-token authentication, automatic ARM connection creation, and the breaking authoring migration warrant final human review.

No open issues 🎉

1 resolved since last review

• Resolve service-key placeholders before endpoint deduplication

_{Review effort: Balanced}

[azure-sdk-automation]

azure.ai.agents PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10631/azure-ai-agents.zip"

• Version: 1.0.0-beta.21.pr.10631.6988049
• Merge commit: 660e4d0