azure.ai.agents: attach and authenticate every toolboxes reference #10621

Describe the bug

Toolbox attachment for Copilot-harness agents currently has two inconsistent YAML fields:

• Singular toolbox is used by the deployment code, but does not automatically configure
  a working authenticated attachment. It adds the Toolbox's MCP URL without creating and
  linking the project connection needed to authenticate. Without that connection, invocation
  fails with HTTP401.
• Plural toolboxes is accepted by the schema, but its entries are not attached.
  Deployment reports success, but the saved agent has no MCP tools for the referenced
  Toolboxes.

There should be one authoring field: toolboxes. Replace the singular path and make each
list entry produce a working authenticated MCP attachment. The user should only reference
the Toolbox service; azd should create or reuse the project connection and link it from the
agent's MCP tool, as shown below.

To reproduce

1. In an initialized azd Foundry project with an existing project and model deployment,
   add a sibling Toolbox and reference it from the agent. Keep the generated project,
   model, agent name and instructions; the relevant service entries are:

   services:
     research-tools:
       host: azure.ai.toolbox
       uses:
         - ai-project
       tools:
         - type: web_search
   
     agent:
       host: azure.ai.agent
       # Keep existing project, model, name, and instructions.
       kind: prompt
       harness:
         type: microsoft_copilot_preview
       uses:
         - ai-project
         - research-tools
       toolboxes:
         - research-tools

   The research-tools service declares the Toolbox independently of the agent's
   toolboxes list. The agent's uses list establishes deployment ordering; toolboxes
   should attach that service's Toolbox to the agent.

2. Run azd deploy --all --no-prompt.

3. Retrieve the saved definition with azd ai agent show --output json.

Actual: agent deployment reports success, but the saved agent has no MCP attachment
for the deployed research-tools Toolbox.

Expected behavior / proposed fix

Use toolboxes as the only supported attachment field. Retire singular toolbox with
a clear migration message to use toolboxes; reject configurations containing both forms.
If compatibility requires a warning period before rejecting singular input, make that
transition explicit.

For every entry in toolboxes, azd should perform these three steps automatically.
The example follows research-tools from the YAML above through to the saved connection
and agent. Assume that service resolves to Toolbox research-tools, version 1.

1. Resolve the Toolbox's deployed MCP URL

Read the endpoint and version published by the research-tools service. In this example:

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/research-tools/versions/1/mcp?api-version=v1

Use the actual deployed resource name and version, not an assumed version or just the YAML
service key.

2. Create or reuse a connection in the Foundry project

For same-project Toolbox access, create the following user-token connection, matching the
working Portal configuration. research-tools-mcp is an example connection name, not a
required naming convention.

{
  "name": "research-tools-mcp",
  "properties": {
    "category": "RemoteTool",
    "authType": "UserEntraToken",
    "audience": "https://ai.azure.com",
    "target": "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/research-tools/versions/1/mcp?api-version=v1",
    "metadata": {
      "type": "toolbox_MCP",
      "toolboxName": "research-tools",
      "toolboxVersion": "1"
    }
  }
}

This connection configures use of the caller's Entra token; do not store a literal token or
API key. Reuse an existing connection only when its target and authentication settings match.
Do not overwrite an incompatible or explicitly configured connection.

3. Reference that connection from the agent's MCP tool

When creating the agent version, add the following MCP entry to definition.tools.
Other agent fields and existing tools are omitted from this JSON excerpt, not removed:

{
  "definition": {
    "tools": [
      {
        "type": "mcp",
        "server_label": "research-tools",
        "server_url": "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/research-tools/versions/1/mcp?api-version=v1",
        "project_connection_id": "research-tools-mcp",
        "require_approval": "always"
      }
    ]
  }
}

project_connection_id belongs on the agent's MCP tool, alongside server_url. Its value
is the name of the project connection created or reused in step 2. It does not go inside
the Toolbox's web_search configuration or require another user-authored YAML field.
The connection's target and the MCP tool's server_url must point to the same endpoint.

Keep azd's existing always approval default unless explicitly configured otherwise. Repeat
steps 1-3 for every referenced Toolbox, preserving other tools and skills. If any required
endpoint or connection cannot be resolved or created, fail deployment with an actionable
error rather than silently omitting the requested attachment.

Acceptance criteria

• One and multiple toolboxes references each produce the expected versioned MCP tools
  and authenticated connection references in the persisted agent definition.
• At least one actual Toolbox tool call succeeds through the released azd workflow;
  multiple-reference coverage proves that every referenced Toolbox can be called.
• Redeployment reuses compatible connections without creating duplicate resources or
  duplicate MCP attachments.
• Missing dependencies, connection setup failures, and singular/mixed-form input produce
  clear diagnostics.
• Existing direct tools, skills, and approval settings are preserved.
• Schema, examples and tests agree on the plural authoring field.

Versions tested

• Azure Developer CLI 1.36.0, macOS ARM64.
• Released default Foundry bundle: Agents 1.0.0-beta.21, Projects 1.0.0-beta.14,
  Toolboxes 1.0.0-beta.11, Connections 1.0.0-beta.10.
• Released Agents source: a0f69c325fa54ec6591fc6bf74dada3b500ea8be.
• Relevant source remains unchanged on main at 6a4502d35f508966c932d22847ac8a0ff7429aff.

Source pointers

• Plural service schema.
• Graph currently reads singular managed.Toolbox.
• Toolbox resolver forwards an optional connection ID.
• MCP injection sets project_connection_id only when supplied.