Create hosted agent toolsets

[therealjohn]

Toolbox support for azd ai agent: enabling developers to connect Azure AI Foundry Toolboxes to their hosted agents across the full CLI lifecycle. Toolboxes expose curated tools (MCP servers, OpenAPI, first-party) through a unified MCP-compatible endpoint with platform-managed auth. This proposal adds a --toolbox flag to run and init, plus azd ai agent toolbox list/show for discovery - so developers can wire tools into their agent without leaving the azd workflow.

Base URL: {project-endpoint}/toolsets API Version: v1 Required Header: Foundry-Features: Toolsets=V1Preview

Operation	Method	URL	Body
List	GET	{project-endpoint}/toolsets?api-version=v1	-
Get	GET	{project-endpoint}/toolsets/{name}?api-version=v1	-
Create	POST	{project-endpoint}/toolsets?api-version=v1	{ "name": "{name}", "description": "{desc}", "metadata": {…}, "tools": [{…}] }
Update	POST	{project-endpoint}/toolsets/{name}?api-version=v1	{ "description": "{desc}", "metadata": {…}, "tools": [{…}] }
Delete	DELETE	{project-endpoint}/toolsets/{name}?api-version=v1	-

Response shapes:

• Single: { "object", "id", "created_at", "updated_at", "name", "description", "metadata", "tools" }
• List: { "data": [ ...toolbox objects ] }
• Delete: { "object", "name", "deleted": true }

1. Agent Manifest: Declare toolbox dependencies as ToolResource

The AgentSchema already supports ToolResource with an open options map, and FoundryConnection for Foundry project auth. No schema changes needed.

# agent-manifest.yaml
resources:
  - name: chat-model
    kind: model
    id: grok-4-fast-non-reasoning

  - name: github-tools
    kind: tool
    id: github-toolbox
    options:
      connection:
        kind: foundry
        endpoint: ${AZURE_AI_PROJECT_ENDPOINT}
        name: github-toolbox
        connectionType: toolbox
      allowedTools:
        - search_docs
        - create_issue

• kind: tool - parsed by ExtractResourceDefinitions() into ToolResource
• id - the toolbox name
• options.connection - uses FoundryConnection (Entra ID auth, project-scoped)
• options.allowedTools - which tools from the toolbox's MCP server the agent uses

2. azure.yaml: Toolboxes as agent config (like deployments)

Toolboxes are project-level resources, but listed as agent config because they are dependencies of the agent - the same pattern as deployments (model deployments are also project-level, but azd ensures they exist as part of deploying the agent).

# azure.yaml
services:
  af-agent-with-foundry-tools:
    host: azure.ai.agent
    project: src/af-agent-with-foundry-tools
    language: docker
    config:
      deployments:
        - name: grok-4-fast-non-reasoning
          model: { format: xAI, name: grok-4-fast-non-reasoning, version: "1" }
          sku: { capacity: 10, name: GlobalStandard }
      Toolboxes:
        - name: github-toolbox
          tools:
            - type: mcp
              server_label: github
              server_url: https://api.githubcopilot.com/mcp
              project_connection_id: GitHubCopilotKey

3. Environment Variables: Named per-toolbox endpoints

Replaces the single AZURE_AI_TOOLBOX_ENDPOINT env var with a naming convention that scales to N Toolboxes:

AZURE_AI_TOOLBOX__GITHUB_TOOLBOX__ENDPOINT=https://<project>.services.ai.azure.com/api/Toolboxes/github-toolbox/mcp
AZURE_AI_TOOLBOX__CORPORATE_TOOLBOX__ENDPOINT=https://<project>.services.ai.azure.com/api/Toolboxes/corporate-toolbox/mcp

Key Decisions

Decision	Rationale
ToolResource in manifest resources[]	Schema already supports it - no changes needed
config.Toolboxes[] in azure.yaml	Agent dependencies, parallel to config.deployments[] - azd ensures they exist
FoundryConnection in manifest options	Correct auth model for Foundry project Toolboxes
Named env vars per toolbox	Replaces single AZURE_AI_TOOLBOX_ENDPOINT, scales to N Toolboxes
Greenfield/brownfield at deploy time	azd checks if toolbox exists > create if missing, skip if present

What Works Today (no changes needed)

• AgentSchema - ToolResource, FoundryConnection schemas exist
• Toolbox API client - toolbox_operations.go has CreateToolbox
• Manifest parsing - ExtractResourceDefinitions() handles kind: tool

What Needs to Change

Area	Change
azure.ai.agent.json schema	Add Toolboxes[] definition (parallel to deployments[])
ServiceTargetAgentConfig	Add Toolboxes []Toolbox field
azd ai agent init -m	Process ToolResource entries > write to config.Toolboxes[] in azure.yaml
Deploy flow	Read config.Toolboxes[], check-or-create via Toolboxes API before agent deploy
azd ai agent listen	Resolve toolbox MCP endpoints > set AZURE_AI_TOOLBOX__<NAME>__ENDPOINT env vars