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" azure-identity 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.

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,
                },
                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.

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.