Início Rápido: Criar uma caixa de ferramentas e usá-la com um agente hospedado

No caso do SDK do Python, use a seção sobre Python mais adiante neste artigo, em vez do fluxo de trabalho do Azure Developer CLI ou do VS Code. Este caminho cria a caixa de ferramentas com project_client.toolboxes.create_version(...), em seguida, carrega o código do agente hospedado como uma nova versão e aponta-o para essa caixa de ferramentas pelo nome.

Instale os pacotes de Python usados neste caminho:

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

Você precisa de um projeto do Foundry existente com um modelo com capacidade de chat implantado. O caminho do Python SDK neste início rápido cria a caixa de ferramentas e a versão do agente hospedado, mas não cria um novo projeto do Foundry ou uma implantação de modelo para você.

Você também precisa do Visual Studio Code com a extensão Caixa de Ferramentas do Microsoft Foundry, conectado ao Azure.

O exemplo inclui um toolbox.yaml em src/toolbox-agent que define as duas ferramentas por trás de um único ponto de extremidade. Crie a caixa de ferramentas desse arquivo:

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

A primeira versão se torna a versão padrão automaticamente. O comando exibe o endpoint MCP versionado da caixa de ferramentas. Copie o Endpoint valor da saída. Defina-a como a TOOLBOX_ENDPOINT variável de ambiente nas próximas etapas. Tem esta aparência:

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

1. Abra Visual Studio Code e selecione o Foundry Toolkit na Barra de Atividades.

2. Entre em sua conta de Azure se for solicitado.

3. Em Meus Recursos, expanda seu projeto e expanda Ferramentas.

4. No modo de exibição Ferramentas , selecione o ícone + Adicionar Caixa de Ferramentas .

5. Insira o nome da caixa de ferramentas (my-toolbox) e uma descrição.

6. Selecione a pesquisa na Web.

7. Selecione + Adicionar ferramenta, escolha adicionar um servidor MCP remoto e insira a URL https://learn.microsoft.com/api/mcpdo servidor. O servidor é público, portanto, nenhuma autenticação é necessária.

8. Selecione Publicar. A publicação cria a primeira versão da caixa de ferramentas.

9. Copie o ponto de extremidade MCP da caixa de ferramentas. Execute o comando a seguir e copie o endpoint valor da saída. Defina-a como a TOOLBOX_ENDPOINT variável de ambiente nas próximas etapas:

   azd ai toolbox show my-toolbox --output json
   

Caminho do SDK do Python

Use as etapas a seguir se quiser criar a caixa de ferramentas e implantar a versão do agente hospedado usando o SDK do Python em vez do fluxo da CLI do Desenvolvedor Azure ou do VS Code.

1. Criar ou escolher um projeto do Foundry

1. Abra o portal do Foundry e crie um projeto do Foundry ou selecione um existente.
2. No projeto, implante um modelo compatível com chat, como gpt-5.4-mini.
3. Copie o endpoint do projeto em Visão geral e o nome da implantação em Build>Deployments.

2. Baixe o exemplo de agente hospedado da caixa de ferramentas

Faça um clone do repositório de exemplos do Foundry:

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

Crie uma pasta de trabalho para os scripts de implantação. Nessa pasta, crie um .env arquivo com estes valores:

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>

Etapa 3: Criar a caixa de ferramentas com Python

Crie um arquivo nomeado create_toolbox.py na mesma pasta de trabalho que .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}")

Executar o script:

python create_toolbox.py

O agente hospedado de exemplo pode resolver a caixa de ferramentas a partir de TOOLBOX_ENDPOINT ou de FOUNDRY_PROJECT_ENDPOINT mais TOOLBOX_NAME. Esse caminho usa TOOLBOX_NAME, então você não precisa armazenar o endpoint versionado em .env.

4. Implantar o agente hospedado com Python

Crie um arquivo nomeado deploy_toolbox_agent.py na mesma pasta de trabalho que .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,
            )

Executar o script:

python deploy_toolbox_agent.py

Este script envia o exemplo do Toolbox como uma nova versão do agente hospedado, aponta temporariamente o agente hospedado para essa versão, invoca-o com uma pergunta do Microsoft Learn e restaura a configuração anterior do endpoint ao finalizar.

5. Verifique a resposta baseada na caixa de ferramentas

Se você configurar a caixa de ferramentas corretamente, a resposta mostra que o agente hospedado descobriu as ferramentas da caixa de ferramentas e respondeu usando a documentação do Microsoft Learn.

Exclua a caixa de ferramentas:

azd ai toolbox delete my-toolbox --force

Depois de excluir a toolbox, o endpoint para de funcionar. Remova-o de src/toolbox-agent/.env e remova-o do seu ambiente azd:

azd env set TOOLBOX_ENDPOINT ""

Exclua o agente e seus recursos de Azure:

azd down

Exclua a caixa de ferramentas por nome:

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

Se você criou um grupo de recursos dedicado ou projeto para este início rápido, exclua-o do portal do Azure depois de não precisar mais da caixa de ferramentas, da implantação de chat ou do agente hospedado.