Snabbstart: Skapa en verktygslåda och använd den med en värdbaserad agent

För sökvägen Python SDK använder du avsnittet Python senare i den här artikeln i stället för arbetsflödet Azure Developer CLI eller VS Code. Den vägen skapar verktygslådan med project_client.toolboxes.create_version(...), laddar sedan upp hosted-agent-koden som en ny version och pekar den mot den verktygslådan med namn.

Installera de Python paket som används i den här sökvägen:

pip install "azure-ai-projects>=2.3.0" python-dotenv

Du behöver ett befintligt Foundry-projekt med en distribuerad chattkompatibel modell. Med Python SDK-spåret i den här snabbstarten skapar du verktygslådan och versionen för den värdbaserade agenten, men det skapar inte något nytt Foundry-projekt eller någon modelldistribution åt dig.

För sökvägen .NET SDK använder du C#-avsnittet senare i den här artikeln i stället för arbetsflödet Azure Developer CLI eller VS Code. Det tillvägagångssättet skapar verktygslådan med AgentToolboxes.CreateVersion(...) och laddar sedan upp den C#-baserade hosted-agent-koden som en ny version och pekar den mot den verktygslådan med namn.

Du behöver också .NET 10 SDK eller senare och ett befintligt Foundry-projekt med en distribuerad chattkompatibel modell.

Du behöver också Visual Studio Code med tillägget Microsoft Foundry Toolkit som är inloggad på Azure.

Exemplet innehåller ett toolbox.yaml i src/toolbox-agent som definierar båda verktygen bakom en slutpunkt. Skapa verktygslådan från filen:

azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml

Den första versionen blir standardversionen automatiskt. Kommandot skriver ut verktygslådans version av MCP-slutpunkten. Kopiera värdet Endpoint från utdata. Ange den som TOOLBOX_ENDPOINT miljövariabel i nästa steg. Det ser ut så här:

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

1. Öppna Visual Studio Code och välj Foundry Toolkit i aktivitetsfältet.

2. Logga in på ditt Azure-konto om du uppmanas att göra det.

3. Under Mina resurser expanderar du projektet och expanderar sedan Verktyg.

4. I vyn Verktyg väljer du ikonen + Lägg till verktygslåda .

5. Ange verktygslådans namn (my-toolbox) och en beskrivning.

6. Välj Webbsökning.

7. Välj + Lägg till verktyg, välj att lägga till en fjärr-MCP-server och ange serverns URL https://learn.microsoft.com/api/mcp. Servern är offentlig, så ingen autentisering krävs.

8. Välj Publicera. Publicering skapar den första versionen av verktygslådan.

9. Kopiera verktygslådans MCP-slutpunkt. Kör följande kommando och kopiera endpoint värdet från utdata. Ange den som TOOLBOX_ENDPOINT miljövariabel i nästa steg:

   azd ai toolbox show my-toolbox --output json
   

sökväg till Python SDK

Använd följande steg om du vill skapa verktygslådan och distribuera den värdbaserade agentversionen med hjälp av Python SDK i stället för Azure Developer CLI- eller VS Code-flödet.

1. Skapa eller välj ett Foundry-projekt

1. Öppna Foundry-portalen och skapa ett Foundry-projekt eller välj ett befintligt.
2. I projektet distribuerar du en chattkompatibel modell som gpt-5.4-mini.
3. Kopiera projektslutpunkten från Översikt och distributionsnamnet frånByggdistributioner>.

2. Ladda ned hosted-agent-exemplet för verktygslådan

Klona lagringsplatsen för Foundry-exempel:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Skapa en arbetsmapp för distributionsskripten. I den mappen skapar du en .env fil med följande värden:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

Steg 3: Skapa verktygslådan med Python

Skapa en fil med namnet create_toolbox.py i samma arbetsmapp som .env:

import os

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

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

Kör skriptet:

python create_toolbox.py

Den värdbaserade agenten kan hitta verktygslådan antingen från TOOLBOX_ENDPOINT eller från FOUNDRY_PROJECT_ENDPOINT samt TOOLBOX_NAME. Den här sökvägen använder TOOLBOX_NAME, så du behöver inte lagra den versionerade slutpunkten i .env.

4. Distribuera den värdbaserade agenten med Python

Skapa en fil med namnet deploy_toolbox_agent.py i samma arbetsmapp som .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                    "PYTHONNOUSERSITE": "1",
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint

        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Kör skriptet:

python deploy_toolbox_agent.py

Det här skriptet laddar upp verktygslådeexemplet som en ny värdbaserad agentversion, pekar den värdbaserade agenten tillfälligt på den versionen, anropar den med en Microsoft Learn-fråga och återställer den tidigare slutpunktskonfigurationen när den är klar.

5. Verifiera det verktygslådebaserade svaret

Om du konfigurerar verktygslådan korrekt visar svaret att den värdbaserade agenten identifierade verktygslådans verktyg och svarade med hjälp av Microsoft Learn-dokumentationen.

sökväg till C# SDK

Använd den här sökvägen för att skapa verktygslådan och distribuera exemplet C# hosted-agent med .NET SDK i stället för arbetsflödet Azure Developer CLI eller VS Code.

1. Skapa eller välj ett Foundry-projekt

1. Öppna Foundry-portalen och skapa ett Foundry-projekt eller välj ett befintligt.
2. I projektet distribuerar du en chattkompatibel modell som gpt-4o.
3. Kopiera projektslutpunkten från Översikt och distributionsnamnet frånByggdistributioner>.

2. Ladda ned hosted-agent-exemplet för verktygslådan

Klona lagringsplatsen för Foundry-exempel:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Exemplet C# hosted-agent finns under samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. Distributionskoden i nästa steg anger dessa miljövariabler i containern:

3. Skapa verktygslådan med C#

Skapa en .NET konsolapp och installera paketen. Api:er för verktygslådan är i förhandsversion, så installera förhandsversionspaketet Azure.AI.Projects :

dotnet new console --name create-toolbox
cd create-toolbox
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Ersätt Program.cs med följande kod och ställ in endpoint på projektslutpunkten:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AgentToolboxes toolboxes = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ToolboxVersion created = toolboxes.CreateVersion(
    name: toolboxName,
    tools:
    [
        new WebSearchToolboxTool { Name = "web_search", SearchContextSize = WebSearchToolSearchContextSize.Medium },
        new MCPToolboxTool(serverLabel: "mslearn")
        {
            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
        },
    ],
    description: "Toolbox with web search and Microsoft Learn MCP.");
Console.WriteLine($"Created toolbox version {created.Version} for {created.Name}");

Kör appen:

dotnet run

Den värdbaserade exempelagenten löser verktygslådan från FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME, så du behöver inte lagra den versionerade slutpunkten.

4. Distribuera den värdbaserade agenten med C#

Skapa en andra konsolapp för distributionskoden:

dotnet new console --name deploy-toolbox-agent
cd deploy-toolbox-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Ersätt Program.cs med följande kod. Ange endpoint, chatModeloch samplePath till dina värden. samplePath är den fullständiga sökvägen till källmappen foundry-toolbox-server-side-dotnet-agent-framework som du klonade i steg 2:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var toolboxName = "my-toolbox";
var agentName = "toolbox-agent";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-toolbox-server-side\src\foundry-toolbox-server-side-dotnet-agent-framework";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-toolbox-server-side.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("TOOLBOX_NAME", toolboxName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);
    ResponseResult response = responsesClient.CreateResponse(
        "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation.");
    Console.WriteLine(response.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Kör appen:

dotnet run

Den här koden laddar upp verktygslådeexemplet som en ny värdbaserad agentversion, pekar den värdbaserade agenten tillfälligt på den versionen, anropar den med en Microsoft Learn-fråga och återställer den tidigare slutpunktskonfigurationen när den är klar.

5. Verifiera det verktygslådebaserade svaret

Om du konfigurerar verktygslådan korrekt visar svaret att den värdbaserade agenten identifierade verktygslådans verktyg och svarade med hjälp av Microsoft Learn-dokumentationen.

Ta bort verktygslådan:

azd ai toolbox delete my-toolbox --force

När du tar bort verktygslådan slutar dess ändpunkt att fungera. Ta bort den från src/toolbox-agent/.env och rensa den från din azd miljö:

azd env set TOOLBOX_ENDPOINT ""

Ta bort agenten och dess Azure resurser:

azd down

Ta bort verktygslådan efter namn:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

Om du har skapat en dedikerad resursgrupp eller ett projekt för den här snabbstarten tar du bort den från Azure portalen när du inte längre behöver verktygslådan, chattdistributionen eller den värdbaserade agenten.

Distributionskoden tar redan bort den värdbaserade agentversionen och återställer den tidigare slutpunktskonfigurationen när den är klar. Om du vill ta bort verktygslådan lägger du till den här koden i en konsolapp som har Azure.AI.Projects (förhandsversion) och Azure.Identity paket installerade:

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

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.AgentAdministrationClient.GetAgentToolboxes().Delete(toolboxName);
Console.WriteLine($"Deleted toolbox '{toolboxName}'.");

Om du har skapat en dedikerad resursgrupp eller ett projekt för den här snabbstarten tar du bort den från Azure portalen när du inte längre behöver verktygslådan, chattdistributionen eller den värdbaserade agenten.