Erstellen, Testen und Bereitstellen einer Toolbox in Foundry

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, ToolboxSearchPreviewTool, WebSearchTool

# Create Foundry project client
endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Create toolbox version with web search and MCP tools
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchTool(),
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolboxSearchPreviewTool(),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

using Azure.Identity;
using Azure.AI.Projects;

// Create Foundry project client
var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool());

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval
    )
));

ToolboxSearchPreviewTool searchTool = new() { Name = "ToolBoxSearch" };

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool, searchTool],
    description: "Toolbox with web search, MCP, and tool search"
);
Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with web search, MCP, and tool search",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    },
    {
      "type": "toolbox_search_preview"
    }
  ]
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Create Foundry project client
const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";

const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "web_search",
      description: "Search the web for current information",
    },
    {
      type: "mcp",
      server_label: "myserver",
      server_url: "https://your-mcp-server.example.com",
      require_approval: "never",
      project_connection_id: "my-key-auth-connection",
    },
    { type: "toolbox_search_preview" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Verwenden Sie das Microsoft Foundry Toolkit für Visual Studio Code Erweiterung, um eine Toolbox aus der Ansicht Tools zu erstellen und zu veröffentlichen.

1. Wählen Sie das Foundry Toolkit in der Aktivitätsleiste aus.
2. Erweitern Sie unter "Meine Ressourcen"Ihren Projektnamen>Tools.
3. Wählen Sie das Symbol "+Toolbox hinzufügen " aus.
4. Geben Sie auf der Registerkarte " Benutzerdefinierte Toolbox erstellen" den Namen und die Beschreibung der Toolbox ein, und fügen Sie die gewünschten Tools hinzu.
5. Wählen Sie zum Aktivieren der absichtsbasierten Toolrouting die Option "Toolsuche" aus.
6. Wählen Sie "Veröffentlichen" aus.

Beim Veröffentlichen einer neuen Toolbox wird die erste Version erstellt. Diese Version wird automatisch zur Standardversion.

Erstellen Sie mit dem einheitlichen microsoft.foundryErweiterungspaket (siehe Voraussetzungen) eine Toolbox in zwei Schritten:

1. Verwenden Sie azd ai connection create, um jede Projektverbindung zu registrieren, auf die die Toolbox verweist (ein Aufruf pro Anmeldeinformationssatz).
2. Verwenden Sie azd ai toolbox create --from-file <toolbox.yaml>, um die Toolbox zu erstellen. Die YAML verweist auf Verbindungen nach Namen und bettet niemals Anmeldeinformationen ein.

Das Muster ist für jede Verbindungsart und jeden Authentifizierungstyp identisch:

1. Legen Sie das aktive Projekt einmal pro Shell fest:

   azd ai project set $PROJECT_ENDPOINT
   

2. Erstellen Sie eine Verbindung mit azd ai connection create. Die Flags unterscheiden sich je nach Authentifizierungstyp, aber die Befehlsstruktur ist immer:

   azd ai connection create <name> \
     --kind <remote-tool|remote-a2a|cognitive-search|GroundingWithCustomSearch> \
     --target <endpoint-url> \
     --auth-type <none|custom-keys|api-key|oauth2|user-entra-token|project-managed-identity|agentic-identity> \
     [--custom-key "Header=Value" | --key <key> | --client-id ... --client-secret ... --authorization-url ... --token-url ... | --audience <aad-resource-uri>]
   

   Verwenden Sie azd ai connection list und azd ai connection show <name>, um Verbindungen zu prüfen, und azd ai connection delete <name> --force, um sie zu entfernen.

3. Erstellen Sie eine Toolbox-YAML, die auf eine oder mehrere vorhandene Verbindungen anhand des Namens verweist. YaML bettet niemals Anmeldeinformationen ein:

   # my-toolbox.yaml
   description: <human-readable description>
   connections:
     - name: <project-connection-name>   # must already exist in the project
   # Optional: add connectionless built-in tools and policies.
   tools:
     - type: web_search
       name: web
     - type: code_interpreter
       container: { type: auto }
       name: code
     # Tool search is connectionless.
     - type: toolbox_search_preview
     # For Azure AI Search, set the index in the tool entry:
     # - type: azure_ai_search
     #   name: search
     #   azure_ai_search:
     #     indexes:
     #       - project_connection_id: <azure-ai-search-connection-name>
     #         index_name: <search-index-name>
     # For Bing Custom Search, set the instance in the tool entry:
     # - type: bing_custom_search
     #   name: bing
     #   custom_search_configuration:
     #     project_connection_id: <bing-connection-name>
     #     instance_name: <bing-instance-name>
   # Optional: attach existing project skills as MCP resources.
   skills:
     - name: <skill-name>          # uses the skill's default version
     - name: <other-skill>
       version: "2"               # pin to a specific skill version (string)
   policies:
     rai_config:
       rai_policy_name: <policy-name>    # must already exist on the project
   

   Mindestens einer von connections, skillsoder tools muss nicht leer sein. Verweise auf Fähigkeiten müssen auf Fähigkeiten verweisen, die bereits im selben Foundry-Projekt vorhanden sind; siehe Fähigkeiten in Foundry verwenden, um sie mit azd ai skill create zu erstellen. Einzelheiten zur Einrichtung der End-to-End-Toolsuche finden Sie unter Toolsuche verwenden.

4. Erstellen Sie die Toolbox aus dieser Datei:

   azd ai toolbox create <toolbox-name> --from-file ./my-toolbox.yaml
   

   Die erste Version wird automatisch zum Standard. Verwenden Sie azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name> und azd ai toolbox delete <name> --force zum Verwalten von Toolboxen.

Beispiel: MCP-Server mit schlüsselbasierter Authentifizierung

# 1. Create the connection
azd ai connection create my-gh-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# 2. Create the toolbox
azd ai toolbox create my-toolbox \
  --from-file ./my-toolbox.yaml \
  --no-prompt

# my-toolbox.yaml
description: GitHub MCP toolbox
connections:
  - name: my-gh-conn

Kopieren Sie in der Erweiterung Microsoft Foundry Toolkit for Visual Studio Code den Verbraucher-Endpunkt der Toolbox aus der Ansicht Toolboxes.

1. Wählen Sie das Foundry Toolkit in der Aktivitätsleiste aus.
2. Erweitern Sie unter "Meine Ressourcen"Ihren Projektnamen>Tools.
3. Suchen Sie auf der Registerkarte "Toolboxes " Ihre Toolbox.
4. Kopieren Sie den Endpunkt in der Spalte "Endpunkt-URL ".

Der Endpunkt-URL-Wert ist der Toolbox-Verbraucherendpunkt. Verwenden Sie das in der vorherigen Tabelle gezeigte Entwicklermuster, um einen versionsspezifischen Endpunkt zu erstellen.

Installieren Sie das MCP-Client-SDK:

pip install mcp

Verbinden Sie sich mit der Toolbox und listen Sie die Werkzeuge auf.

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            # Call a tool (replace with actual tool name and arguments)
            result = await session.call_tool("<tool_name>", arguments={})
            print(result)

asyncio.run(verify_toolbox())

Verwenden Sie den versionsspezifischen Endpunkt (/versions/{version}/mcp), um eine Version zu überprüfen, bevor Sie sie bewerben.

1. Initialisieren der MCP-Sitzung:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Senden Sie die initialisierte Benachrichtigung:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. Verfügbare Tools auflisten:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

4. Aufrufen eines Tools:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<TOOL_NAME>","arguments":{}}}

Installieren Sie das MCP-Client-SDK:

npm install @modelcontextprotocol/sdk

Verbinden Sie sich mit der Toolbox und listen Sie die Werkzeuge auf.

import { DefaultAzureCredential } from "@azure/identity";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1";

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");

const transport = new StreamableHTTPClientTransport(
  new URL(url),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${token.token}`,
      },
    },
  },
);

const client = new Client({ name: "test", version: "1.0" });
await client.connect(transport);

// List available tools
const toolsResult = await client.listTools();
console.log(`Tools found: ${toolsResult.tools.length}`);
for (const tool of toolsResult.tools) {
  console.log(`  - ${tool.name}: ${(tool.description || "").slice(0, 80)}`);
}

// Call a tool (replace with actual tool name and arguments)
const result = await client.callTool({ name: "<tool_name>", arguments: {} });
console.log(result);

await client.close();

Verwenden Sie den Endpunkt aus Schritt 2 zusammen mit einer Gerüstvorlage für gehostete Agenten, um die Toolbox-Ladung in Visual Studio Code zu validieren.

1. Suchen Sie im Foundry Toolkit unter Meine Ressourcen>dein Projektname>Tools die Toolbox, die Sie testen möchten.
2. Wählen Sie "Scaffold Code-Template" aus.
3. Wählen Sie einen Projektordner aus, wenn Sie dazu aufgefordert werden.
4. Folgen Sie der generierten README.md, um Abhängigkeiten zu installieren, Umgebungsvariablen zu konfigurieren und das Beispiel lokal auszuführen.
5. Verwenden Sie Agent Inspector oder führen Sie python main.py aus, um zu bestätigen, dass die Werkzeuge der Toolbox geladen werden und reagieren.

Verwenden Sie für die versionsspezifische Überprüfung in diesem Schritt die Python- oder REST-API-Registerkarte, bevor Sie eine neue Toolbox-Version veröffentlichen.

LangGraph

Sehen Sie sich das vollständige Beispiel für die vollständige Implementierung an.

.env Datei:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (Schlüsselmuster):

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name=TOOLBOX_NAME)
tools = await toolbox.get_tools()

Microsoft Agent Framework

Verwenden Sie MCPStreamableHTTPTool aus dem Agent Framework SDK, um direkt eine Verbindung zum MCP-Endpunkt der Toolbox herzustellen.

.env Datei:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (Schlüsselmuster):

# Auth: wrap token provider in an httpx.Auth subclass
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
http_client = httpx.AsyncClient(
    auth=_ToolboxAuth(token_provider),
    timeout=120.0,
)

# Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_ENDPOINT)
TOOLBOX_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1"

# Connect MCPStreamableHTTPTool to the toolbox endpoint
mcp_tool = MCPStreamableHTTPTool(
    name="toolbox",
    url=TOOLBOX_ENDPOINT,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="my-toolbox-agent",
    instructions="You are a helpful assistant with access to Foundry toolbox tools.",
    tools=[mcp_tool],
)
ResponsesAgentServerHost().run()

Sehen Sie sich das vollständige Beispiel für die vollständige Implementierung an.

Copilot SDK

Verwenden Sie das GitHub Copilot SDK, um einen auf Toolbox basierenden Agenten zu erstellen, der die Werkzeugaufrufe von Copilot mit dem MCP-Endpunkt der Foundry-Toolbox verbindet.

.env Datei:

GITHUB_TOKEN=<your-github-token>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

agent.py (Schlüsselmuster — MCP-Brücke):

# 1. Open an MCP session to the toolbox endpoint
bridge = McpBridge(endpoint=TOOLBOX_ENDPOINT, token=_get_toolbox_token())
await bridge.initialize()
mcp_tools = await bridge.list_tools()

# 2. Map MCP tool list to Copilot SDK tool definitions
#    Dots in tool names are replaced with underscores (Copilot SDK requirement)
copilot_tools = [
    {
        "name": t["name"].replace(".", "_"),
        "description": t.get("description", ""),
        "parameters": t.get("inputSchema", {}),
    }
    for t in mcp_tools
]

# 3. Wire tool calls back to the MCP session
async def tool_handler(name: str, arguments: dict) -> str:
    return await bridge.call_tool(name.replace("_", ".", 1), arguments)

# 4. Run the Copilot SDK agent
agent = Agent(
    tools=copilot_tools,
    tool_handler=tool_handler,
    token=os.environ["GITHUB_TOKEN"],
)

Microsoft Agent Framework

Verwenden Sie ResponsesServer aus dem Agent Framework SDK mit einem benutzerdefinierten ToolboxMcpClient, um Tools der Toolbox über den MCP-Endpunkt zu ermitteln und aufzurufen.

Umgebungsvariablen:

AZURE_OPENAI_ENDPOINT=https://<account>.services.ai.azure.com
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_MCP_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

Program.cs (Schlüsselmuster):

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

// Azure OpenAI endpoint and model deployment
var openAiEndpoint = "https://<account>.services.ai.azure.com";
var deployment = "gpt-4o";  // supports all toolbox tool types

// Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_MCP_ENDPOINT)
var toolboxEndpoint = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1";

// Azure OpenAI client
var credential = new DefaultAzureCredential();
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
var chatClient = openAIClient.GetChatClient(deployment);

// Toolbox MCP client — discovers tools via tools/list, calls them via tools/call
var toolboxClient = new ToolboxMcpClient(toolboxEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

ToolboxMcpClient umschließt direkte JSON-RPC Aufrufe an den MCP-Endpunkt. ToolboxHandler verbindet LLM-Toolaufrufe mithilfe einer standardmäßigen Toolaufrufschleife wieder mit dem MCP-Client. Die vollständige Implementierung beider Klassen finden Sie im vollständigen Beispiel.

Verwenden Sie die Microsoft Foundry Toolkit-Erweiterung für Visual Studio Code, um das Grundgerüst für eine Beispielanwendung für einen gehosteten Agenten zu erstellen, die bereits mit Ihrer Toolbox verbunden ist.

1. Wählen Sie das Foundry Toolkit in der Aktivitätsleiste aus.
2. Erweitern Sie unter "Meine Ressourcen"Ihren Projektnamen>Tools.
3. Suchen Sie auf der Registerkarte Toolboxes die Toolbox, die Sie verwenden möchten, und wählen Sie dann die Gerüstcodevorlage aus.
4. Wählen Sie in der Befehlspalette einen Projektordner aus, wenn Sie dazu aufgefordert werden.
5. Öffnen Sie das generierte README.md Element, und folgen Sie den Setup-, lokalen Ausführungs- und Bereitstellungsschritten für das Gerüst.

Das generierte Projekt beinhaltet den Einstiegspunkt des Hosted Agents, Bereitstellungsdateien und eine README.md-Datei mit den genauen Schritten für Einrichtung, Ausführung und Bereitstellung.

Wenn Sie eine Toolbox in ein vorhandenes gehostetes Agent-Projekt integrieren möchten, anstatt ein neues Beispiel zu generieren, verwenden Sie den kopierten Endpunkt aus Schritt 2 mit den Python- oder .NET-Mustern in diesem Abschnitt.

Übergeben Sie den Toolbox-Endpunkt an Ihren Agenten

Nachdem Sie die Toolbox in Schritt 1 erstellt haben, rufen Sie den MCP-Endpunkt mit azd ai toolbox show und übergeben diesen Endpunkt als Umgebungsvariable an Ihren Agentcode. Der Agent liest die Variable beim Start und verwendet sie zum Herstellen einer Verbindung mit der Toolbox.

1. Rufen Sie den Toolbox-Endpunkt ab:

   azd ai toolbox show <toolbox-name> --output json
   

   Das Feld mcp_endpoint in der Antwort ist der Consumerendpunkt, der immer in den default_version der Toolbox aufgelöst wird.

2. Legen Sie den Endpunkt als Umgebungsvariable fest, die Ihr Agent beim Start liest:

   # .env (or however your runtime loads environment variables)
   TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1
   

3. Lesen Sie in Ihrem Agentcode TOOLBOX_ENDPOINT und verbinden Sie sich mit ihm über einen MCP-Client. Verwenden Sie die Python oder .NET Integrationsmuster weiter oben in diesem Abschnitt als Referenz für die Clienteinrichtung und das Entra-Token (https://ai.azure.com/.default Bereich).

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    tools=[
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="always",  # "always" | "never"
            project_connection_id="my-connection",
        )
    ],
)

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always",
      "project_connection_id": "my-connection"
    }
  ]
}

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )
));

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    require_approval: "always",
    project_connection_id: "my-connection",
  },
];

Verwenden Sie die Registerkarte Python, .NET, JavaScript, REST-API oder azd, um require_approval in Ihrer Toolboxdefinition zu konfigurieren. Der Workflow der Erweiterung „Microsoft Foundry Toolkit für Visual Studio Code“ in diesem Artikel konzentriert sich auf das Erstellen und Verwenden der Toolbox in Visual Studio Code.

resources:
  - kind: toolbox
    name: my-toolbox
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        require_approval: always
        project_connection_id: my-connection

# Create a new toolbox version
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "<toolbox-name>",
    tools: [tool],
    description: "Updated tools v2"
);
Console.WriteLine($"Created version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Updated tools v2",
  "tools": [...]
}

const toolboxVersion = await project.toolboxes.createVersion(
  "<toolbox-name>",
  [/* tools array */],
  { description: "Updated tools v2" },
);
console.log(`Created version: ${toolboxVersion.version}`);

Verwenden Sie die Registerkarte Python, .NET, JavaScript oder REST-API, um eine neue Toolboxversion zu erstellen. Der Workflow der Erweiterung Microsoft Foundry Toolkit für Visual Studio Code, der in diesem Artikel beschrieben wird, konzentriert sich auf das Erstellen einer Toolbox und das Generieren des Grundgerüsts für einen gehosteten Agenten, der sie verwendet.

Dieser Vorgang wird mit der Azure Developer CLI nicht unterstützt. Verwenden Sie zum Erstellen einer Toolboxversion die Registerkarte Python, .NET, REST-API oder JavaScript.

# List all toolbox versions
versions = list(project.toolboxes.list_toolbox_versions(name="<toolbox-name>"))
for v in versions:
    print(f"{v.version} — created {v.created_at}")

List<ToolboxVersion> versions = await toolboxClient
    .GetToolboxVersionsAsync("<toolbox-name>")
    .ToListAsync();
Console.WriteLine($"Found {versions.Count} toolbox version(s).");
foreach (ToolboxVersion v in versions)
{
    Console.WriteLine($"  - {v.Name} ({v.Version})");
}

GET {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}

const versions = project.toolboxes.listVersions("<toolbox-name");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.created_at}`);
}

Verwenden Sie die Registerkarte Python, .NET, JavaScript oder REST-API, um Toolboxversionen aufzulisten.

# The current default version is marked with *
azd ai toolbox version list <toolbox-name>

# Get a specific toolbox version
version_obj = project.toolboxes.get_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

ToolboxVersion versionObj = await toolboxClient.GetToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Retrieved toolbox: {versionObj.Name} ({versionObj.Id})");

GET {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

const versionObj = await project.toolboxes.getVersion(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Retrieved version: ${versionObj.version}`);

Verwenden Sie die Registerkarte Python, .NET, JavaScript oder REST-API, um eine bestimmte Toolboxversion abzurufen.

azd ai toolbox version get <toolbox-name> <version_id>

# Promote a version to default
toolbox = project.toolboxes.update(
    toolbox_name="<toolbox-name>",
    default_version="<version_id>",
)
print(f"Active version: {toolbox.default_version}")

ToolboxRecord record = await toolboxClient.UpdateToolboxAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Active version: {record.DefaultVersion}");

PATCH {project_endpoint}/toolboxes/<toolbox-name>?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "default_version": "<version_id>"
}

default_version darf nicht leer sein. Ersetzen Sie sie durch eine neue Version.

const toolbox = await project.toolboxes.update(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Active version: ${toolbox.default_version}`);

Verwenden Sie die Registerkarte Python, .NET, JavaScript oder REST-API, um eine Toolboxversion als Standard festzulegen.

Toolboxversionen sind unveränderlich. Verwenden Sie publish, um eine vorhandene Version zur neuen Standardversion zu machen:

# Roll back or forward to a specific version
azd ai toolbox publish <toolbox-name> <version_id> --no-prompt

publish ist der einzige Weg, mit dem default_version über die CLI geändert wird; mutierende Verben (connection add/remove, skill add/remove) erstellen immer eine neue Version, ohne sie heraufzustufen.

# Delete a toolbox version
project.toolboxes.delete_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

await toolboxClient.DeleteToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);

DELETE {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

await project.toolboxes.deleteVersion(
  "<toolbox-name>",
  "<version_id>",
);

Verwenden Sie die Registerkarte Python, .NET, JavaScript oder REST-API, um eine Toolboxversion zu löschen.

Dieser Vorgang wird mit der Azure Developer CLI nicht unterstützt. Verwenden Sie zum Löschen einer Toolboxversion die Registerkarte Python, .NET, REST-API oder JavaScript.

Schlüsselbasierte Authentifizierung:

{
  "description": "my-mcp-toolbox",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "my-mcp-connection"
    }
  ]
}

Keine Authentifizierung (öffentlicher MCP-Server):

{
  "description": "Public MCP server",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com"
    }
  ]
}

OAuth oder identitätsbasierte Authentifizierung:

Erstellen Sie für OAuth (verwalteter Connector, benutzerdefinierte App-Registrierung), Agentidentität oder Benutzer-Entra-Tokenauthentifizierung zuerst die entsprechende Verbindung in Ihrem Foundry-Projekt, und verweisen Sie darauf mit project_connection_id:

{
  "description": "MCP server with OAuth/identity auth",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "<OAUTH_OR_IDENTITY_CONNECTION_NAME>"
    }
  ]
}

Die Verbindung authType bestimmt den Authentifizierungsfluss. Unterstützte Verbindungsauthentifizierungstypen für MCP umfassen CustomKeys, OAuth2 (verwaltet oder benutzerdefiniert), AgenticIdentityTokenund UserEntraToken. Sehen Sie sich auf der Registerkarte azd Beispiele für Verbindungskonfigurationen für die einzelnen Authentifizierungstypen an.

from azure.ai.projects.models import MCPTool

tools = [
    MCPTool(
        server_label="myserver",
        server_url="https://your-mcp-server.example.com",
        project_connection_id="my-mcp-connection",
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com")
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "my-mcp-toolbox"
);

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    project_connection_id: "my-mcp-connection",
  },
];

Erstellen Sie eine Projektverbindung für Ihren MCP-Server mit dem Authentifizierungstyp, der Ihrem Szenario entspricht, und verweisen Sie dann aus einer minimalen Toolbox-YAML darauf.

Schritt 1. Erstellen der Verbindung

PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
azd ai project set $PROJECT_ENDPOINT

Wählen Sie die Authentifizierungsvariante aus, die Sie benötigen:

# No auth — public MCP server
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://learn.microsoft.com/api/mcp \
  --auth-type none

# Custom-keys header (for example, GitHub PAT)
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# OAuth — bring your own app registration
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://your-mcp-server.example.com \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# User Entra token (managed user identity passthrough; for example, Microsoft Fabric)
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://api.fabric.microsoft.com/v1/mcp/fabricaihub/integrations/m365 \
  --auth-type user-entra-token \
  --audience https://analysis.windows.net/powerbi/api

# Project managed identity — the project's system-assigned MI
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://<resource>.cognitiveservices.azure.com/language/mcp \
  --auth-type project-managed-identity \
  --audience https://cognitiveservices.azure.com

# Agentic identity — the agent's per-project identity
azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://<resource>.cognitiveservices.azure.com/language/mcp \
  --auth-type agentic-identity \
  --audience https://cognitiveservices.azure.com

Weisen Sie bei identitätsbasierter Authentifizierung (user-entra-token, project-managed-identity, agentic-identity) dem entsprechenden Prinzipal die erforderliche RBAC-Rolle für die Zielressource zu, bevor Sie die Toolbox aufrufen.

Schritt 2. Definieren der Toolbox

# my-toolbox.yaml
description: MCP server tools
connections:
  - name: my-mcp-conn

Schritt 3: Erstellen der Toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Built-in web search",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>"
    }
  ]
}

Mit einer Verbindung mit „Grounding mit benutzerdefinierter Bing-Suche“:

{
  "description": "Custom Bing Search instance",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "web_search": {
        "custom_search_configuration": {
          "project_connection_id": "<BING_CONNECTION_NAME>",
          "instance_name": "<BING_INSTANCE_NAME>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import WebSearchTool

tools = [
    WebSearchTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool()
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Built-in web search"
);

const tools = [
  {
    type: "web_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
  },
];

Standard (Grounding mit Bing-Suche, keine Verbindung erforderlich):

# my-toolbox.yaml
description: Web search toolbox
tools:
  - type: web_search

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Verankerung mit Bing Custom Search:

# Step 1. Create the Bing Custom Search connection
azd ai connection create my-bing-custom \
  --kind GroundingWithCustomSearch \
  --target https://api.bing.microsoft.com/ \
  --auth-type api-key \
  --key "<bing-custom-search-key>"

--kind GroundingWithCustomSearch erfordert exakte PascalCase-Schreibweise.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Bing Custom Search toolbox
connections:
  - name: my-bing-custom
    instance_name: your-bing-custom-instance

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Azure AI Search over my data",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

from azure.ai.projects.models import AzureAISearchTool

tools = [
    AzureAISearchTool(
        index_name="<INDEX_NAME>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new AzureAISearchTool(
    new AzureAISearchToolOptions(
        indexes: [
            new AzureAISearchIndexResource(
                indexName: "<INDEX_NAME>",
                projectConnectionId: "<CONNECTION_NAME>"
            )
        ]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Azure AI Search over my data"
);

const tools = [
  {
    type: "azure_ai_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    azure_ai_search: {
      indexes: [
        {
          index_name: "<INDEX_NAME>",
          project_connection_id: "<CONNECTION_NAME>",
        },
      ],
    },
  },
];

# Step 1. Create the Azure AI Search connection
azd ai connection create my-search \
  --kind cognitive-search \
  --target "https://<your-search>.search.windows.net/" \
  --auth-type api-key \
  --key "<aisearch-admin-key>"

cognitive-search Verbindungen akzeptieren auch --auth-type project-managed-identity (kein Schlüssel). Wenn Sie projektverwaltete Identität verwenden, weisen Sie die vom System zugewiesene verwaltete Identität des Projekts der Rolle "Suchindexdatenleser " im Suchdienst zu.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Azure AI Search toolbox
connections:
  - name: my-search
    index: your-index-name

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Code interpreter for data analysis",
  "tools": [
    {
      "type": "code_interpreter",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "container": {
            "type": "auto",
            "file_ids": ["<FILE_ID>"]
        }
    }
  ]
}

from azure.ai.projects.models import CodeInterpreterTool

tools = [
    CodeInterpreterTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateCodeInterpreterTool(
        new CodeInterpreterToolContainer()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Code interpreter for data analysis"
);

const tools = [
  {
    type: "code_interpreter",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    container: {
      type: "auto",
      file_ids: ["<FILE_ID>"],
    },
  },
];

Code Interpreter ist verbindungslos. Deklarieren Sie sie direkt unter tools:.

# my-toolbox.yaml
description: Code interpreter toolbox
tools:
  - type: code_interpreter
    container: { type: auto }

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Search over uploaded documents",
  "tools": [
    {
      "type": "file_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "file_search": {
        "vector_store_ids": ["<VECTOR_STORE_ID>"]
      }
    }
  ]
}

from azure.ai.projects.models import FileSearchTool

tools = [
    FileSearchTool(
        vector_store_ids=["<VECTOR_STORE_ID>"]
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateFileSearchTool(
        vectorStoreIds: ["<VECTOR_STORE_ID>"]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Search over uploaded documents"
);

const tools = [
  {
    type: "file_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    file_search: {
      vector_store_ids: ["<VECTOR_STORE_ID>"],
    },
  },
];

Die Dateisuche ist ohne Verbindung, erfordert jedoch eine vorhandene Vektorspeicher-ID. Deklarieren Sie sie direkt unter tools:.

# my-toolbox.yaml
description: File search toolbox
tools:
  - type: file_search
    vector_store_ids:
      - vs_xxxxxxxxxxxx

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Anonyme Authentifizierung:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Projekt-Authentifizierung:

Verwenden Sie dieses Muster, wenn für die API ein Schlüssel oder Token erforderlich ist, der in einer Foundry-Projektverbindung gespeichert ist.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Verwaltete Identitätsauthentifizierung:

Verwenden Sie dieses Muster, wenn sich die Ziel-API über Microsoft Entra ID authentifiziert. Die verwaltete Identität des Foundry-Projekts ruft die API im Namen des Agents auf. Stellen Sie sicher, dass die verwaltete Identität über die erforderliche RBAC-Rolle für den Zieldienst verfügt, bevor Sie dieses Muster verwenden.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

OpenAPI-Tools betten die Spezifikation direkt unter tools: ein. Verbindungsbasierte Authentifizierung (connection_auth) verweist auf eine Projektverbindung. Anonyme OpenAPI-Tools benötigen keine Verbindung.

Schritt 1. (Optional) Erstellen der Authentifizierungsverbindung

Überspringen Sie diesen Schritt für anonyme OpenAPI-Tools.

# API-key auth (passed by the platform on every call)
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer <token>"

OpenAPI-Tools akzeptieren auch --auth-type oauth2 Verbindungen. Den vollständigen Satz von azd ai connection create Flags finden Sie oben im MCP-Abschnitt.

Schritt 2. Definieren der Toolbox

Die OpenAPI-Spezifikation ist inline unter tools[].openapi.spec.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

Ersetzen Sie den auth: Block für anonyme APIs durch:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Schritt 3: Erstellen der Toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Delegate tasks to a specialist agent",
  "tools": [
    {
      "type": "a2a_preview",
      "name": "<AGENT_NAME>",
      "description": "<What this agent does>",
      "base_url": "<AGENT_BASE_URL>",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

from azure.ai.projects.models import A2APreviewTool

tools = [
    A2APreviewTool(
        name="<AGENT_NAME>",
        description="<What this agent does>",
        base_url="<AGENT_BASE_URL>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new A2APreviewTool()
{
    ProjectConnectionId = "<CONNECTION_NAME>",
};

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Delegate tasks to a specialist agent"
);

const tools = [
  {
    type: "a2a_preview",
    name: "<AGENT_NAME>",
    description: "<What this agent does>",
    base_url: "<AGENT_BASE_URL>",
    project_connection_id: "<CONNECTION_NAME>",
  },
];

Erstellen Sie eine remote-a2a Verbindung für den Remote-Agent, und verweisen Sie dann aus einer minimalen Toolbox-YAML darauf.

Schritt 1. Erstellen der Verbindung

Wählen Sie die Authentifizierungsvariante aus, die Sie benötigen:

# No auth
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type none

# Custom-keys header
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer <token>"

# OAuth — bring your own app registration
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# User Entra token (managed user identity passthrough)
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type user-entra-token \
  --audience "<entra-audience>"

# Project managed identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type project-managed-identity \
  --audience "<entra-audience>"

# Agentic identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type agentic-identity \
  --audience "<entra-audience>"

Schritt 2. Definieren der Toolbox

# my-toolbox.yaml
description: Agent-to-Agent toolbox
connections:
  - name: my-a2a-conn

Schritt 3: Erstellen der Toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Fabric IQ for enterprise Fabric data access",
  "tools": [
    {
      "type": "fabric_iq_preview",
      "project_connection_id": "<CONNECTION_NAME>",
      "server_label": "<SERVER_LABEL>",
      "server_url": "<SERVER_URL>"
    }
  ]
}

tools = [
    {
        "type": "fabric_iq_preview",
        "project_connection_id": "<CONNECTION_NAME>",
        "server_label": "<SERVER_LABEL>",
        "server_url": "<SERVER_URL>",
    }
]

Fabric IQ wird als MCP-Endpunkt bedient. Erstellen Sie eine remote-tool Verbindung mit dem Fabric IQ-Server mit user-entra-token (empfohlen; die Identität des Anrufers wird an Fabric weitergeleitet), und verweisen Sie dann aus einer minimalen Toolbox-YAML darauf.

# Step 1. Create the Fabric IQ connection
azd ai connection create my-fabric-conn \
  --kind remote-tool \
  --target https://api.fabric.microsoft.com/v1/mcp/fabricaihub/integrations/m365 \
  --auth-type user-entra-token \
  --audience https://analysis.windows.net/powerbi/api

remote-tool Verbindungen akzeptieren auch --auth-type oauth2. Den vollständigen Flagsatz finden Sie oben im MCP-Abschnitt.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Fabric IQ (semantic model)
tools:
  - type: fabric_iq_preview
    project_connection_id: my-fabric-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Toolbox with intent-based tool routing",
  "tools": [
    {
      "type": "toolbox_search_preview"
    }
  ]
}

tools = [
    {"type": "toolbox_search_preview"}
]

Tool Search ist verbindungslos. Deklarieren Sie sie direkt unter tools:.

# my-toolbox.yaml
description: Toolbox with intent-based tool routing
tools:
  - type: toolbox_search_preview

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Wählen Sie im Foundry Toolkit für Visual Studio Code Toolsuche auf der Registerkarte Build a Custom Toolbox aus, wenn Sie eine Toolbox erstellen oder bearbeiten. Weitere Informationen finden Sie unter Aktivieren der Toolsuche in einer Toolbox.

{
  "description": "Work IQ for Microsoft 365 data access",
  "tools": [
    {
      "type": "work_iq_preview",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

tools = [
    {
        "type": "work_iq_preview",
        "project_connection_id": "<CONNECTION_NAME>",
    }
]

Work IQ wird als A2A-Endpunkt bedient. Erstellen Sie eine remote-a2a-Verbindung zum Work IQ-Server mit oauth2, und verweisen Sie anschließend mit einem minimalen Toolbox-YAML darauf.

# Step 1. Create the Work IQ connection
azd ai connection create my-workiq-conn \
  --kind remote-a2a \
  --target https://agent365.svc.cloud.microsoft/agents/agents/workiq \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/common/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/common/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Work IQ toolbox
tools:
  - type: work_iq_preview
    project_connection_id: my-workiq-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

{
  "description": "Perform actions using a real web browser",
  "tools": [
    {
      "type": "browser_automation_preview",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "browser_automation_preview": {
        "connection": {
          "project_connection_id": "<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import (
    BrowserAutomationPreviewTool,
    BrowserAutomationToolParameters,
    BrowserAutomationToolConnectionParameters,
)

tools = [
    BrowserAutomationPreviewTool(
        browser_automation_preview=BrowserAutomationToolParameters(
            connection=BrowserAutomationToolConnectionParameters(
                project_connection_id="<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>",
            )
        )
    )
]

ProjectsAgentTool tool = new BrowserAutomationPreviewTool(
    new BrowserAutomationToolOptions(
        new BrowserAutomationToolConnectionParameters("<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>")
    )
);

const tools = [
  {
    type: "browser_automation_preview",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    browser_automation_preview: {
      connection: {
          project_connection_id: "<BROWSER_AUTOMATION_PROJECT_CONNECTION_ID>"
      }
    }
  },
];

# Step 1. Create the Playwright Workspace connection
azd ai connection create my-browser-conn \
  --kind PlaywrightWorkspace \
  --target wss://your-browser-endpoint.api.playwright.microsoft.com/playwrightworkspaces/browsers \
  --auth-type api-key \
  --key "<playwright-workspaces-access-token>"

--kind PlaywrightWorkspace erfordert exakte PascalCase-Schreibweise.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Browser Automation toolbox
tools:
  - type: browser_automation_preview
    project_connection_id: my-browser-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WebSearchTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchTool()],
    policies={
        "rai_config": {
            "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
        }
    },
)
print(f"Created version: {toolbox_version.version}")

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with guardrail",
  "tools": [{ "type": "web_search" }],
  "policies": {
    "rai_config": {
      "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
    }
  }
}

#pragma warning disable AAIP001
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

var toolboxVersion = toolboxClient.CreateToolboxVersion(
    toolboxName: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchTool()],
    policies: new ToolboxPolicies
    {
        RaiConfig = new RaiConfig { RaiPolicyName = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>" }
    });
Console.WriteLine($"Created version: {toolboxVersion.Version}");

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [{ type: "web_search" }],
  {
    description: "Toolbox with guardrail",
    policies: {
      rai_config: {
        rai_policy_name: "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>",
      },
    },
  },
);
console.log(`Created version: ${toolboxVersion.version}`);

name: my-toolbox
description: Toolbox with guardrail
policies:
  rai_config:
    rai_policy_name: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>
tools:
  - type: web_search

Die Guardrail-Konfiguration ist in der VS Code-Erweiterung noch nicht verfügbar. Verwenden Sie die REST-API, das SDK oder azd, um Leitplanken zu konfigurieren.

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Foundry-Features: Skills=V1Preview

{
  "description": "Toolbox with a skill reference",
  "tools": [],
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting"
    }
  ]
}

So heften Sie eine bestimmte Version an:

{
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting",
      "version": "v1"
    }
  ]
}

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="v1"),  # pin to v1
    ],
)
print(f"Created toolbox version: {toolbox_version.id}")

#pragma warning disable AAIP001
// Reuse the AgentToolboxes client (toolboxClient) from Step 1.
ToolboxSkillReference skillRef = new("greeting");
// To pin a version: new ToolboxSkillReference("greeting") { Version = "v1" }

ToolboxVersion toolboxVersion = toolboxClient.CreateToolboxVersion(
    name: "my-toolbox",
    tools: [],
    skills: [skillRef],
    description: "Toolbox with a skill reference"
);
Console.WriteLine($"Created toolbox version: {toolboxVersion.Id}");

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [],
  {
    description: "Toolbox with a skill reference",
    skills: [
      { type: "skill_reference", name: "greeting" },
      // { type: "skill_reference", name: "greeting", version: "v1" },  // pin to v1
    ],
  },
);
console.log(`Created toolbox version: ${toolboxVersion.id}`);

Die Azure Developer CLI unterstützt Skillverweise an zwei Stellen: deklarativ als skills:-Block auf oberster Ebene in der azd ai toolbox create --from-file-YAML-Datei und imperativ mit den azd ai toolbox skill add/list/remove-Verben. Jeder Verweis erfordert ein name (erforderlich) und ein optionales version (Zeichenfolge). Lassen Sie version aus, um der default_version des Skills zu folgen. Geben Sie eine Versionszeichenfolge an, um die Toolbox auf einen unveränderlichen Snapshot festzulegen.

Deklarieren von Fähigkeiten beim Erstellen der Toolbox

# my-toolbox.yaml
description: Toolbox with skill references
connections:
  - name: my-gh-conn
skills:
  - name: greeting              # follows the skill's default version
  - name: review-checklist
    version: "2"               # pin to skill version 2

azd ai toolbox create my-toolbox --from-file ./my-toolbox.yaml --no-prompt

Hinzufügen, Auflisten und Entfernen von Fähigkeiten in einer vorhandenen Toolbox

# Add a skill (follows default version)
azd ai toolbox skill add my-toolbox greeting

# Add a skill pinned to a specific version
azd ai toolbox skill add my-toolbox review-checklist@2

# Add multiple skills from a file (same shape as the create YAML's skills block)
azd ai toolbox skill add my-toolbox --from-file ./skills.yaml

# List skill references on the current default version
azd ai toolbox skill list my-toolbox --output table

# Remove a skill (--force skips the confirmation prompt; multiple names allowed)
azd ai toolbox skill remove my-toolbox greeting --force

skill list zeigt nur die Standardversion an. Angeheftete Skills zeigen ihre Version, nicht angeheftete Skills hingegen zeigen (default). Um Skills in einer ausstehenden Version zu überprüfen, führen Sie azd ai toolbox show <toolbox> --version <n> --output json aus, und lesen Sie das Array skills.

Qualifikationsnamen müssen übereinstimmen ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (Kleinbuchstaben, Ziffern und Bindestriche; max. 64 Zeichen; kein führendes oder nachfolgendes Bindestrich). Eine nachfolgende @ in <name>@<version> (eine leere Version) wird abgelehnt.

Qualifikationsverweise können derzeit nicht über die VS Code-Erweiterung konfiguriert werden. Verwenden Sie die REST-API oder das SDK, um Fähigkeiten zu konfigurieren.

Überprüfen der Fähigkeitserkennung

Überprüfen Sie nach dem Anfügen von Fähigkeiten an eine Toolboxversion, ob sie über den MCP-Endpunkt der Toolbox mithilfe des MCP Python SDK auffindbar sind:

import asyncio
from azure.identity import DefaultAzureCredential
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def list_skills():
    credential = DefaultAzureCredential()
    token = credential.get_token("https://ai.azure.com/.default").token
    toolbox_url = "{endpoint}/toolboxes/my-toolbox/mcp?api-version=v1"
    headers = {
        "Authorization": f"Bearer {token}",
    }
    async with streamablehttp_client(toolbox_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            resources = await session.list_resources()
            for resource in resources.resources:
                print(f"Skill: {resource.uri} - {resource.name}")

asyncio.run(list_skills())

Fähigkeiten werden als MCP-Ressourcen mit URIs im Format skill://{name}angezeigt.

Fähigkeiten aus einem Agent nutzen (Microsoft Agent Framework, .NET)

Verwenden Sie in .NET AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) aus dem Microsoft Agent Framework SDK, um MCP-basierte Fähigkeiten von einem Toolboxendpunkt zu ermitteln und sie als AIContextProviders auf dem Agent einzubringen. Der Agent lädt dann zur Laufzeit die Anweisungen der einzelnen Skills, wenn das Modell entscheidet, dass sie relevant sind. Im folgenden Program.cs wird der Agent mit der Hostebene „Antworten“ (AddFoundryResponses und MapFoundryResponses) gehostet.

using System.Net.Http.Headers;
using Azure.AI.Projects;
using Azure.Core;
using Azure.Identity;
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Load .env file if present (for local development).
Env.TraversePath().Load();

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.");

string deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.");

string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME environment variable is not set.");

// Build the Foundry Toolbox MCP URL from the project endpoint and toolbox name.
string toolboxMcpServerUrl = $"{projectEndpoint.TrimEnd('/')}/toolboxes/{toolboxName}/mcp?api-version=v1";

TokenCredential credential = new DefaultAzureCredential();

// HttpClient that attaches a fresh Foundry bearer token to every request.
// CheckCertificateRevocationList = true satisfies CA5399.
using var httpClient = new HttpClient(
    new BearerTokenHandler(credential, "https://ai.azure.com/.default")
    {
        CheckCertificateRevocationList = true,
    });

Console.WriteLine($"Connecting to Foundry Toolbox '{toolboxName}' MCP server...");

// Connect to the Foundry Toolbox MCP endpoint.
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new HttpClientTransportOptions
        {
            Endpoint = new Uri(toolboxMcpServerUrl),
            Name = toolboxName,
            TransportMode = HttpTransportMode.StreamableHttp,
        },
        httpClient));

// AgentSkillsProvider implements progressive disclosure over the MCP-discovered skills:
// names and descriptions are advertised in the system prompt, and the full skill body
// (and any supplementary resources) is loaded on demand when the model decides it is
// relevant.
var skillsProvider = new AgentSkillsProviderBuilder()
    .UseMcpSkills(mcpClient)
    .Build();

AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "foundry-toolbox-mcp-skills",
        Description = "Agent that discovers MCP-based skills from a Foundry Toolbox and exposes them via AgentSkillsProvider.",
        ChatOptions = new ChatOptions
        {
            ModelId = deployment,
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

// HttpClientHandler that attaches a fresh Foundry bearer token to every outgoing request.
internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : HttpClientHandler
{
    private readonly TokenRequestContext _tokenContext = new([scope]);

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}

Das vollständige Beispiel, einschließlich Projektdateien und Bereitstellungsschritte, finden Sie im Beispiel "Skills in Toolbox".