Início rápido: Constrói uma caixa de ferramentas e usa-a com um agente alojado

Importante

Os itens assinalados como (pré-visualização) neste artigo estão atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para trabalhos em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Neste quickstart, constróis uma caixa de ferramentas que combina duas ferramentas num único endpoint gerido:

Pesquisa na web, que fundamenta as respostas em resultados públicos em tempo real.
O servidor MCP Microsoft Learn, que fundamenta as respostas na documentação oficial da Microsoft. É um endpoint público que não requer autenticação.

Depois consomes a caixa de ferramentas de um agente hospedado escrito em Python. A caixa de ferramentas expõe um endpoint MCP, por isso o agente liga-se a uma única URL e descobre todas as ferramentas em tempo de execução. Podes mudar as ferramentas mais tarde sem alterar o código do agente.

Se usares um agente de programação como o GitHub Copilot, o Microsoft Foundry Skill pode ajudar a construir o endpoint toolbox, ligá-lo a um agente alojado e ajustar as ferramentas de exemplo.

Pré-requisitos

Este início rápido baseia-se na cadeia de ferramentas do agente hospedado. Complete primeiro os Pré-requisitos no quickstart do agente alojado, que abrangem a subscrição do Azure, funções de projeto, Python, a CLI do Azure Developer (azd) e a microsoft.foundry extensão.

Para o caminho do SDK Python, use a secção Python mais adiante neste artigo em vez do Azure Developer CLI ou do fluxo de trabalho do VS Code. Esse caminho cria a caixa de ferramentas com project_client.toolboxes.create_version(...), depois 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 Python usados neste caminho:

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

Precisas de um projeto Foundry já existente com um modelo de chat implementado. O procedimento com o SDK de Python neste quickstart cria a toolbox e a versão do agente alojado, mas não cria um novo projeto Foundry nem uma implantação de modelo.

Também precisa de Visual Studio Code com a extensão Microsoft Foundry Toolkit, com sessão iniciada no Azure.

Passo 1: Inicializar o agente hospedado

Inicialize um agente hospedado a partir da amostra da caixa de ferramentas Foundry, que se liga a uma caixa de ferramentas através do MCP e expõe as suas ferramentas ao modelo. Cria a toolbox (my-toolbox) no passo seguinte e aponta o agente para o respetivo endpoint. Executa estes comandos num diretório vazio.

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src src/toolbox-agent

Siga as instruções para selecionar o seu projeto e um modelo de implementação existente. Quando lhe pedirem para selecionar alocação de recursos de contentores, escolha 1 núcleo, memória 2Gi. A imagem do contentor do agente requer mais do que o escalão predefinido. A opção --src cria a estrutura base do agente em src/toolbox-agent.

Observação

Manifestos de agente (agent.manifest.yaml) e definições de agentes independentes (agent.yaml) estão obsoletos. A partir das extensões Foundry azd (azure.ai.agents 1.0.0-beta.1), toda a configuração de agentes alojados reside num único azure.yaml. Consulte Autor azure.yaml para agentes alojados.

Passo 2: Criar a caixa de ferramentas

Cria a caixa de ferramentas e depois copia o endpoint MCP que ele devolve. Define esse endpoint como variável de ambiente nos passos seguintes.

O azure.yaml exemplo define a caixa de ferramentas como um serviço azure.ai.toolbox e liga-a ao serviço de agente alojado com uses:. Se alterares a configuração da toolbox, edita o serviço da toolbox em azure.yaml, não em src/toolbox-agent/agent.yaml.

Primeiro, aponte os comandos da caixa de ferramentas para o projeto Foundry que selecionou durante a inicialização. Reutilize o endpoint que a inicialização já armazenou no seu ambiente azd:

azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value FOUNDRY_PROJECT_ENDPOINT)"

O exemplo inclui um toolbox.yaml em src/toolbox-agent que define as duas ferramentas num único endpoint. Crie a caixa de ferramentas a partir desse ficheiro:

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

A primeira versão torna-se automaticamente a versão padrão. O comando imprime o endpoint MCP versionado da toolbox. Copie o Endpoint valor da saída. Defina como variável TOOLBOX_ENDPOINT de ambiente nos próximos passos. Tem a seguinte aparência:

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

Abra o Visual Studio Code e selecione Foundry Toolkit na Barra de Atividades.
Inicia sessão na tua conta Azure se te pedirem.
Na secção Meus Recursos, expanda o seu projeto e depois expanda as Ferramentas.
Na vista de Ferramentas, selecione o ícone + Adicionar Caixa de Ferramentas.
Introduza o nome da caixa de ferramentas (my-toolbox) e uma descrição.
Selecione pesquisa na Web.
Selecione + Adicionar ferramenta, escolha adicionar um servidor MCP remoto e introduza o URL https://learn.microsoft.com/api/mcpdo servidor . O servidor é público, por isso não é necessária autenticação.
Selecione Publicar. Ao publicar, é criada a primeira versão da caixa de ferramentas.
Copie o endpoint MCP da caixa de ferramentas. Execute o comando seguinte e copie o endpoint valor da saída. Defina-o como variável TOOLBOX_ENDPOINT de ambiente nos próximos passos:
```
azd ai toolbox show my-toolbox --output json
```

Passo 3: Provisionar recursos Azure

O agente lê o endpoint MCP da caixa de ferramentas a partir da variável de ambiente TOOLBOX_ENDPOINT, que azure.yaml obtém do seu ambiente azd. Define esse valor nos passos seguintes. Provisione os recursos Azure do agente:

azd provision

Passo 4: Executar o agente localmente

Aponte o agente local para a sua caixa de ferramentas definindo estes valores no .env ficheiro em src/toolbox-agent. Cole o endpoint que copiou no Passo 2:
```
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>
```
azd ai agent run injeta FOUNDRY_PROJECT_ENDPOINT e lê o .env ficheiro para execuções locais. O exemplo trata da ligação à toolbox, dos cabeçalhos e da autenticação por si.
Inicie o agente:
```
azd ai agent run
```
Este comando cria um ambiente virtual, instala dependências e serve o agente em http://localhost:8088. Os pacotes de pré-visualização podem gerar avisos de pip durante a configuração. Estes avisos não são impeditivos.

Num terminal separado, envie prompts que exerçam as ferramentas:

azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
azd ai agent invoke --local "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation."

Passo 5: Implementar no Serviço Foundry Agent

Guarda o endpoint que copiaste no Step 2 no teu azd ambiente, que azure.yaml se resolve no momento da implementação. Depois constrói e implementa o contentor agente:

azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy

Quando o comando termina, a saída mostra links para o ambiente de testes do agente e para o ponto final do agente. Invocar o agente destacado:

azd ai agent invoke "What's new in Microsoft Foundry? Use the Microsoft Learn documentation."

Caminho do SDK Python

Use os passos seguintes se quiser criar a caixa de ferramentas e implementar a versão do agente hospedado usando o SDK Python em vez do CLI do Azure Developer ou do fluxo do VS Code.

1. Criar ou escolher um projeto Foundry

Abra o portal Foundry e crie um projeto Foundry, ou selecione um já existente.
No projeto, implemente um modelo capaz de chat, como gpt-5.4-mini.
Copie o endpoint do projeto de Descrição geral e o nome da implantação de Build>Implantações.

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

Clone o repositório de exemplos do Foundry:

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

Cria uma pasta funcional para os scripts de implementação. Nessa pasta, crie um .env ficheiro 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>

Passo 3: Crie a caixa de ferramentas com Python

Crie um ficheiro 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 alojado de exemplo pode localizar o conjunto de ferramentas tanto a partir de TOOLBOX_ENDPOINT como de FOUNDRY_PROJECT_ENDPOINT mais TOOLBOX_NAME. Este caminho usa TOOLBOX_NAME, por isso não precisa de armazenar o endpoint versionado em .env.

4. Implementar o agente alojado com Python

Crie um ficheiro 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 carrega o exemplo da toolbox como uma nova versão do agente alojado, aponta temporariamente o agente alojado para essa versão, invoca-o com uma pergunta do Microsoft Learn e restaura a configuração anterior do endpoint quando esta termina.

5. Verificar a resposta suportada pela caixa de ferramentas

Se configurares corretamente a caixa de ferramentas, a resposta mostra que o agente alojado descobriu as ferramentas da caixa de ferramentas e respondeu com recurso à documentação do Microsoft Learn.

Limpeza de recursos

Elimine os recursos quando tiver terminado para deixar de incorrer em custos.

Apaga a caixa de ferramentas:

azd ai toolbox delete my-toolbox --force

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

azd env set TOOLBOX_ENDPOINT ""

Apague o agente e os seus recursos do Azure:

Advertência

Se o ambiente atual azd criou o projeto Foundry, azd down apaga permanentemente o grupo de recursos do projeto e tudo o que nele existe. Se selecionou um projeto existente durante a inicialização, azd down deixa o projeto, o seu grupo de recursos, o agente alojado e outros recursos de início rápido no local. Para eliminar recursos que já não precisa do projeto existente, elimine-os separadamente.

azd down

Elimina 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 criaste um grupo de recursos ou projeto dedicado para este quickstart, apaga-o do portal do Azure depois de já não precisares da caixa de ferramentas, do chat ou do agente alojado.

Troubleshooting

Issue	Solução
`tools/list`não retorna ferramentas do Microsoft Learn	Confirme que a ferramenta `mslearn` em `toolbox.yaml` aponta para `https://learn.microsoft.com/api/mcp`.
O agente começa mas reporta `TOOLBOX_ENDPOINT is set but empty` ou não tem ferramentas	Defina `TOOLBOX_ENDPOINT` para o endpoint com versão do Passo 2 em `.env` para execuções locais e execute `azd env set TOOLBOX_ENDPOINT "<endpoint>"` antes de implementar.
As chamadas ao endpoint da toolbox falham com um erro de autorização	Confirme que cada pedido inclui um token Entra com o âmbito de `https://ai.azure.com/.default`. O exemplo trata disto por si.
`Connection refused` em execução local	Certifique-se de que nenhum outro processo está a usar porta `8088`.

O que aprendeste

Neste guia de início rápido, você irá:

Construí uma caixa de ferramentas que combina pesquisa web e o servidor MCP do Microsoft Learn atrás de um único endpoint.
Consumi a caixa de ferramentas de um agente hospedado em Python que se liga através do Model Context Protocol usando o Azure Developer CLI ou o Python SDK.
Executei o agente localmente ou validei-o remotamente e implementei-o no Foundry Agent Service.

Passo seguinte

Adicione uma base de conhecimento Foundry IQ a um agente alojado

Comentários

Esta página foi útil?

Last updated on 2026-07-23