Quickstart: Een werkset bouwen en gebruiken met een gehoste agent

Voor het Python SDK-pad gebruikt u de sectie Python verderop in dit artikel in plaats van de Azure Developer CLI of VS Code-werkstroom. Die route maakt de toolbox met project_client.toolboxes.create_version(...), uploadt vervolgens de code van de hosted-agent als een nieuwe versie en verwijst die versie vervolgens op naam naar die toolbox.

Installeer de Python pakketten die in dit pad worden gebruikt:

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

U hebt een bestaand Foundry-project nodig met een geïmplementeerd model dat geschikt is voor chats. Met de Python SDK-route in deze quickstart maak je de toolbox en de hosted-agentversie, maar er wordt niet automatisch een nieuw Foundry-project opgezet en ook geen modelimplementatie voor je aangemaakt.

U hebt ook Visual Studio Code nodig met de Microsoft Foundry Toolkit-extensie, aangemeld bij Azure.

Het voorbeeld bevat een toolbox.yaml in src/toolbox-agent die beide hulpprogramma's achter één eindpunt definieert. Maak de werkset op basis van dat bestand:

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

De eerste versie wordt automatisch de standaardversie. Met de opdracht wordt het MCP-endpoint met versienummer van de toolbox weergegeven. Kopieer de Endpoint waarde uit de uitvoer. Stel deze in de volgende stappen in als de TOOLBOX_ENDPOINT omgevingsvariabele. Dit ziet er als volgt uit:

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

1. Open Visual Studio Code en selecteer Foundry Toolkit in de activiteitenbalk.

2. Meld u aan bij uw Azure-account als u hierom wordt gevraagd.

3. Vouw onder Mijn resources uw project uit en vouw vervolgens Hulpprogramma's open.

4. Selecteer in de Tools-weergave het pictogram + Toolbox toevoegen.

5. Voer de naam van de werkset (my-toolbox) en een beschrijving in.

6. Selecteer Zoeken op internet.

7. Selecteer + Hulpprogramma toevoegen, kies ervoor om een externe MCP-server toe te voegen en voer de server-URL https://learn.microsoft.com/api/mcpin. De server is openbaar, dus er is geen verificatie vereist.

8. Selecteer Publiceren. Als u publiceert, wordt de eerste versie van de werkset gemaakt.

9. Kopieer het MCP-eindpunt van de werkset. Voer de volgende opdracht uit en kopieer de endpoint waarde uit de uitvoer. Stel deze in de volgende stappen in als de TOOLBOX_ENDPOINT omgevingsvariabele:

   azd ai toolbox show my-toolbox --output json
   

Pad naar Python SDK

Gebruik de volgende stappen als u de werkset wilt maken en de versie van de hosted-agent wilt implementeren met behulp van de Python SDK in plaats van de Azure Developer CLI of VS Code-stroom.

1. Een Foundry-project maken of kiezen

1. Open de Foundry-portal en maak een Foundry-project of selecteer een bestaand project.
2. Implementeer in het project een model dat geschikt is voor chats, zoals gpt-5.4-mini.
3. Kopieer het projecteindpunt uit Overzicht en de implementatienaam uit Build>Deployments.

2. Download het hosted-agent-voorbeeld van de toolbox

Kloon de Foundry-voorbeeldrepository:

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

Maak een werkmap voor de implementatiescripts. Maak in die map een .env bestand met deze waarden:

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>

Stap 3: De werkset maken met Python

Maak een bestand met de naam create_toolbox.py in dezelfde werkmap als .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}")

Voer het script uit:

python create_toolbox.py

De gehoste voorbeeldagent kan de toolbox ophalen vanuit TOOLBOX_ENDPOINT of vanuit FOUNDRY_PROJECT_ENDPOINT in combinatie met TOOLBOX_NAME. Dit pad maakt gebruik van TOOLBOX_NAME, zodat u het versie-eindpunt niet hoeft op te slaan in .env.

4. Implementeer de gehoste agent met Python

Maak een bestand met de naam deploy_toolbox_agent.py in dezelfde werkmap als .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,
            )

Voer het script uit:

python deploy_toolbox_agent.py

Met dit script wordt het werksetvoorbeeld geüpload als een nieuwe versie van een gehoste agent, wordt de gehoste agent tijdelijk naar die versie verwezen, wordt het aangeroepen met een Microsoft Learn-vraag en wordt de vorige eindpuntconfiguratie hersteld wanneer deze is voltooid.

5. Controleer het antwoord vanuit de toolbox

Als u de werkset correct configureert, ziet u in het antwoord dat de gehoste agent de werksethulpprogramma's heeft gedetecteerd en beantwoord met behulp van Microsoft Learn-documentatie.

Verwijder de gereedschapskist:

azd ai toolbox delete my-toolbox --force

Nadat u de toolbox hebt verwijderd, werkt het eindpunt niet meer. Verwijder het uit src/toolbox-agent/.env en wis deze uit uw azd omgeving:

azd env set TOOLBOX_ENDPOINT ""

Verwijder de agent en de bijbehorende Azure resources:

azd down

Verwijder de werkset op naam:

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

Als u voor deze quickstart een toegewezen resourcegroep of project hebt gemaakt, verwijdert u deze uit de Azure-portal nadat u de werkset, chatimplementatie of gehoste agent niet meer nodig hebt.