Tworzenie przybornika i zarządzanie nim w narzędziu Foundry

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, ToolSearchToolboxTool, WebSearchToolboxTool

# 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_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchToolboxTool(),
        MCPToolboxTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolSearchToolboxTool(),
    ],
)
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();

WebSearchToolboxTool webTool = new();
MCPToolboxTool mcpTool = new(serverLabel: "myserver")
{
  ServerUri = new Uri("https://your-mcp-server.example.com"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};

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

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "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"
    }
  ]
}

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" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Użyj rozszerzenia Microsoft Foundry Toolkit dla programu Visual Studio Code, aby utworzyć i opublikować zestaw narzędzi w widoku Tools.

1. Wybierz pozycję Foundry Toolkit na pasku działań.
2. W obszarze Moje zasoby rozwiń Twoją nazwę projektu>Narzędzia.
3. Wybierz ikonę + Dodaj przybornik.
4. Na karcie Tworzenie niestandardowego przybornika wprowadź nazwę i opis przybornika, a następnie dodaj odpowiednie narzędzia.
5. Aby włączyć routing narzędzi oparty na intencjach, wybierz pozycję Wyszukiwanie narzędzi.
6. Wybierz Publikuj.

Opublikowanie nowego przybornika powoduje utworzenie pierwszej wersji. Ta wersja staje się domyślną wersją automatycznie.

Korzystając z ujednoliconego pakietu microsoft.foundry rozszerzeń (zobacz sekcję Wymagania wstępne), utwórz zestaw narzędzi w dwóch krokach:

1. Użyj azd ai connection create, aby zarejestrować każde połączenie projektu, do którego odwołuje się przybornik (jedno wywołanie na każdy rekord poświadczeń).
2. Użyj azd ai toolbox create --from-file <toolbox.yaml>, aby utworzyć przybornik. YaML odwołuje się do połączeń według nazwy i nigdy nie osadza poświadczeń.

Wzorzec jest taki sam dla każdego rodzaju połączenia i typu uwierzytelniania:

1. Ustaw aktywny projekt raz na powłokę:

   azd ai project set $PROJECT_ENDPOINT
   

2. Utwórz połączenie za pomocą polecenia azd ai connection create. Flagi różnią się w zależności od typu uwierzytelniania, ale kształt polecenia jest zawsze:

   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>]
   

   Użyj polecenia azd ai connection list i azd ai connection show <name> , aby sprawdzić połączenia i azd ai connection delete <name> --force usunąć je.

3. Utwórz przybornik YAML, który odwołuje się do co najmniej jednego istniejącego połączenia według nazwy. Kod YAML nigdy nie osadza poświadczeń:

   # 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
     # 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: web_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
   

   Co najmniej jeden z connections, skills lub tools musi być niepusty. Odwołania do umiejętności muszą wskazywać umiejętności, które już istnieją w tym samym projekcie Foundry; zobacz Używanie umiejętności w Foundry, aby utworzyć je za pomocą azd ai skill create. Aby uzyskać szczegółowe informacje na temat kompleksowej konfiguracji wyszukiwania narzędzi, zobacz Korzystanie z wyszukiwania narzędzi.

4. Utwórz zestaw narzędzi na podstawie tego pliku:

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

   Pierwsza wersja staje się domyślna automatycznie. Użyj azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name> i azd ai toolbox delete <name> --force, aby zarządzać panelami narzędzi.

Przykład: serwer MCP z uwierzytelnianiem opartym na kluczach

# 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

W rozszerzeniu Microsoft Foundry Toolkit for Visual Studio Code skopiuj punkt końcowy odbiorcy przybornika z widoku Toolboxes.

1. Wybierz pozycję Foundry Toolkit na pasku działań.
2. W obszarze Moje zasoby rozwiń Twoją nazwę projektu>Narzędzia.
3. Na karcie Przyborniki znajdź przybornik.
4. W kolumnie Adres URL punktu końcowego skopiuj punkt końcowy.

Wartość Adres URL punktu końcowego to punkt końcowy odbiorcy narzędzia. Aby utworzyć punkt końcowy specyficzny dla wersji, użyj wzorca dewelopera pokazanego w poprzedniej tabeli.

Zainstaluj zestaw SDK klienta MCP:

pip install mcp

Połącz się z przybornikiem i wymień narzędzia

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())

Użyj punktu końcowego specyficznego dla wersji (/versions/{version}/mcp), aby zweryfikować wersję przed jej promocją.

1. Zainicjuj sesję MCP:

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. Wyślij zainicjowane powiadomienie:

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. Lista dostępnych narzędzi:

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. Wywołaj narzędzie:

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":{}}}

Zainstaluj zestaw SDK klienta MCP:

npm install @modelcontextprotocol/sdk

Połącz się z przybornikiem i wymień narzędzia

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();

Użyj punktu końcowego MCP zestawu narzędzi wraz z przykładowym hostowanym agentem utworzonym na podstawie szablonu, aby sprawdzić ładowanie zestawu narzędzi w VS Code.

1. W Foundry Toolkit, pod Moje zasoby>Twoja nazwa projektu>Narzędzia, znajdź zestaw narzędzi, który chcesz przetestować.
2. Wybierz szablon kodu szkieletu.
3. Po wyświetleniu monitu wybierz folder projektu.
4. Postępuj zgodnie z wygenerowanymi README.md instrukcjami, aby zainstalować zależności, skonfigurować zmienne środowiskowe i uruchomić przykład lokalnie.
5. Użyj Agent Inspector lub uruchom python main.py, aby potwierdzić ładowanie i reagowanie narzędzi przybornika.

Aby zweryfikować wersję przed promocją nowej wersji przybornika, użyj karty Python lub interfejsu API REST w tym kroku.

LangGraph

Wymagania dotyczące fragmentu integracji hostowanej: Zainstaluj program langchain-azure-ai[tools]>1.2.3. W tym fragmencie użyto AzureAIProjectToolbox; aby uzyskać pełnego agenta, zestaw pakietów i pliki wdrożeniowe, użyj utrzymywanego przykładu LangGraph.

.env plik:

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 (wzorzec klucza):

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Microsoft — Struktura agentów

Zainstaluj agent-framework-foundry, oprócz wymaganego pakietu Azure Identity. Pełną implementację znajdziesz w utrzymywanym przykładzie Agent Framework.

Użyj FoundryToolbox z zestawu SDK Agent Framework, aby połączyć się z punktem końcowym toolbox. Klasa obsługuje uwierzytelnianie zestawu narzędzi i przekazuje kontekst wywołania agenta hostowanego.

.env plik:

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 (wzorzec klucza):

from agent_framework.foundry import FoundryToolbox
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# 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"

toolbox = FoundryToolbox(
    credential,
    url=TOOLBOX_ENDPOINT,
)

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

zestaw SDK Copilot

Wymagania dotyczące fragmentu integracji hostowanej: Zainstaluj zestaw SDK GitHub Copilot dla środowiska uruchomieniowego. Zarys zależy od pomocników McpBridge i _get_toolbox_token należących do aplikacji, które nie są tutaj zaimplementowane. Postępuj zgodnie z istniejącymi wzorcami integracji punktów końcowych przybornika i uwierzytelniania oraz wzorcami integracji hostowanego agenta. Zachowana pełna próbka nie jest jeszcze dostępna.

Użyj zestawu SDK GitHub Copilot, aby zbudować agenta opartego na narzędziowniku, który łączy wywołanie narzędzia Copilot z punktem końcowym MCP narzędziownika Foundry.

.env plik:

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 (wzorzec klucza — mostek MCP)

# 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 — Struktura agentów

Zainstaluj Microsoft.Agents.AI.Foundry.Hosting i Azure.Identity. Aby zapoznać się z kompletnym projektem, zobacz publiczny przykład hosted-toolbox dla platformy Agent Framework.

Użyj AddFoundryToolboxes, aby zarejestrować co najmniej jeden zestaw narzędzi za pomocą hostowanego agenta. Integracja ustala zarządzany punkt końcowy MCP, uwierzytelnia żądania i uwzględnia stan narzędzi w próbie gotowości.

Zmienne środowiskowe:

AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_NAME=<toolbox-name>

Program.cs (wzorzec klucza):

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable(
    "AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME is not set.");

var credential = new DefaultAzureCredential();
AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with access to toolbox tools.",
        name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxName);

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

Użyj rozszerzenia Microsoft Foundry Toolkit dla programu Visual Studio Code, aby wygenerować szkielet przykładu hostowanego agenta, który jest już połączony z Twoim zestawem narzędzi.

1. Wybierz pozycję Foundry Toolkit na pasku działań.
2. W obszarze Moje zasoby rozwiń Twoją nazwę projektu>Narzędzia.
3. Na karcie Przyborniki znajdź przybornik, który chcesz użyć, a następnie wybierz szablon kodu Scaffold.
4. W Palecie Poleceń wybierz folder projektu po wyświetleniu powiadomienia.
5. Otwórz wygenerowany README.md plik i wykonaj kroki instalacji, uruchamiania lokalnego i wdrażania dla szkieletu.

Wygenerowany projekt obejmuje punkt wejścia hostowanego agenta, pliki wdrożeniowe oraz README.md z dokładnymi instrukcjami konfiguracji, uruchamiania i wdrażania.

Jeśli chcesz zintegrować zestaw narzędzi z istniejącym projektem hostowanego agenta, zamiast generować nowy przykład, użyj punktu końcowego MCP zestawu narzędzi ze wzorcami dla języka Python lub platformy .NET w tej sekcji.

Przekaż punkt końcowy Toolbox swojemu agentowi

Po utworzeniu zestawu narzędzi pobierz jego punkt końcowy MCP za pomocą azd ai toolbox show i przekaż go do kodu agenta jako zmienną środowiskową. Agent odczytuje zmienną podczas uruchamiania i używa jej do połączenia się z zestawem narzędzi.

1. Uzyskaj punkt końcowy narzędzia Toolbox:

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

   Pole endpoint w odpowiedzi identyfikuje wybraną wersję. Użyj jej do przetestowania tej wersji przed podwyższeniem poziomu. W przypadku agenta, który powinien korzystać z default_version, skonstruuj punkt końcowy odbiorcy bez wersji pokazany w sekcji Uzyskiwanie punktu końcowego MCP zestawu narzędzi.

2. Ustaw punkt końcowy jako zmienną środowiskową, którą agent odczytuje podczas uruchamiania:

   # .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. W kodzie agenta odczytaj TOOLBOX_ENDPOINT go i nawiąż z nim połączenie za pomocą klienta MCP. Użyj wzorców integracji dla języka Python lub platformy .NET, opisanych wcześniej w tej sekcji, jako punktu odniesienia przy konfiguracji klienta i zakresu tokenu Entra (https://ai.azure.com/.default zakres).

from azure.ai.projects.models import MCPToolboxTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    tools=[
        MCPToolboxTool(
            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"
    }
  ]
}

MCPToolboxTool mcpTool = new(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",
  },
];

Użyj karty Python, .NET, JavaScript, interfejsu API REST lub Azure Developer CLI, aby skonfigurować require_approval w definicji zestawu narzędzi. Omówiony w tym artykule przepływ pracy rozszerzenia Microsoft Foundry Toolkit for Visual Studio Code koncentruje się na tworzeniu i korzystaniu z przybornika w programie 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_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "<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}`);

Użyj karty interfejsu API Python, .NET, JavaScript lub REST, aby utworzyć nową wersję skrzynki narzędziowej. W tym artykule opisano przepływ pracy rozszerzenia Microsoft Foundry Toolkit for Visual Studio Code, koncentrujący się na tworzeniu zestawu narzędzi i wygenerowaniu szkieletu hostowanego agenta, który z niego korzysta.

Ta operacja nie jest obsługiwana w interfejsie wiersza polecenia dewelopera Azure. Aby utworzyć wersję przybornika, skorzystaj z zakładki Python, .NET, REST API lub 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}`);
}

Użyj karty interfejsu API Python, .NET, JavaScript lub REST, aby wyświetlić listę wersji przybornika.

# 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}`);

Użyj zakładki API Python, .NET, JavaScript lub REST, aby uzyskać określoną wersję pakietu narzędzi.

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 nie może być pusty. Zastąp ją nową wersją.

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

Użyj karty Python, .NET, JavaScript lub REST API, aby ustawić wersję przybornika jako domyślną.

Wersje zestawu narzędzi są niezmienialne. Użyj publish polecenia , aby ustawić dowolną istniejącą wersję jako nową domyślną:

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

publish jest jedyną ścieżką, która zmienia default_version z poziomu CLI; czasowniki modyfikujące (connection add/remove, skill add/remove) zawsze tworzą nową wersję bez promowania jej.

# 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>",
);

Użyj karty interfejsu API Python, .NET, JavaScript lub REST, aby usunąć wersję przybornika.

Ta operacja nie jest obsługiwana w interfejsie wiersza polecenia dewelopera Azure. Aby usunąć wersję przybornika, skorzystaj z zakładki Python, .NET, REST API lub JavaScript.

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

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

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchToolboxTool()],
    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.CreateVersion(
  name: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchToolboxTool()],
    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.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

Konfiguracja poręczy nie jest jeszcze dostępna w rozszerzeniu programu VS Code. Użyj interfejsu API REST, zestawu SDK lub interfejsu wiersza polecenia dla deweloperów Azure, aby skonfigurować zabezpieczenia.

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"
    }
  ]
}

Aby przypiąć określoną wersję:

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

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="1"),  # pin to version 1
    ],
)
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 = "1" }

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

const toolboxVersion = await project.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}`);

Interfejs wiersza polecenia platformy Azure dla deweloperów obsługuje odwołania do umiejętności w dwóch miejscach: deklaratywnie jako blok najwyższego poziomu skills: w pliku YAML azd ai toolbox create --from-file oraz imperatywnie za pomocą czasowników azd ai toolbox skill add/list/remove. Każde odwołanie przyjmuje name (wymagane) oraz opcjonalnie version (ciąg znaków). Pomiń version, aby stosować default_version umiejętności; przypnij ciąg wersji, aby zablokować zestaw narzędzi do niezmiennej migawki.

Określ umiejętności podczas tworzenia przybornika

# 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

Dodawanie, wyświetlanie i usuwanie umiejętności w istniejącym przyborniku

# 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 wyświetla tylko wersję domyślną. Przypięte umiejętności wyświetlają swoją wersję; nieprzypięte umiejętności wyświetlają (default). Aby sprawdzić skille w wersji oczekującej, uruchom azd ai toolbox show <toolbox> --version <n> --output json i odczytaj tablicę skills.

Nazwy umiejętności muszą być zgodne z ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (małe litery, cyfry i łączniki; maksymalnie 64 znaki; bez łącznika na początku ani na końcu). Końcowe @ w <name>@<version> (pusta wersja) jest odrzucane.

Odwołań do umiejętności nie można obecnie konfigurować za pomocą rozszerzenia VS Code. Konfigurowanie umiejętności przy użyciu interfejsu API REST lub zestawu SDK.

Weryfikuj wykrywanie umiejętności

Po dołączeniu umiejętności do wersji przybornika sprawdź, czy można je wykryć za pośrednictwem punktu końcowego MCP przybornika przy użyciu zestawu MCP Python SDK:

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())

Umiejętności są wyświetlane jako zasoby MCP z identyfikatorami URI w formacie skill://{name}.

Korzystanie z umiejętności agenta (Microsoft Agent Framework, .NET)

W .NET użyj AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) z zestawu SDK Microsoft Agent Framework, aby odkrywać umiejętności oparte na MCP z punktu końcowego zestawu narzędzi i wstrzyknąć je do agenta jako AIContextProviders. Następnie agent ładuje instrukcje poszczególnych umiejętności w czasie wykonywania, gdy model zdecyduje, że jest to istotne. Poniższe Program.cs hostuje agenta z warstwą hostingu Responses (AddFoundryResponses i MapFoundryResponses).

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);
    }
}

Aby zapoznać się z kompletnym przykładem, w tym plikami projektu i instrukcjami wdrażania, zobacz Skills in Toolbox sample.