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

Neste guia de início rápido, você cria um kit de ferramentas que combina duas ferramentas em um único endpoint gerenciado:

• Pesquisa na Web, que fundamenta respostas em resultados da Web públicos em tempo real.
• O servidor mcp do Microsoft Learn, que fundamenta respostas na documentação oficial do Microsoft. É um endpoint público que não exige autenticação.

Em seguida, você consome a caixa de ferramentas de um agente hospedado escrito em Python. O kit de ferramentas expõe um endpoint MCP, de modo que o agente se conecta a uma única URL e descobre todas as ferramentas em tempo de execução. Você pode alterar as ferramentas posteriormente sem alterar o código do agente.

Pré-requisitos

Este guia de início rápido se baseia no conjunto de ferramentas do agente hospedado. Conclua os pré-requisitos no início rápido do agente hospedado primeiro, que abrangem a assinatura Azure, as funções de projeto, Python, a CLI do Desenvolvedor do Azure (azd) e a microsoft.foundry extensão.

Para o caminho do VS Code, você também precisa Visual Studio Code com a extensão Microsoft Foundry Toolkit, conectado ao Azure.

Etapa 1: inicializar o agente hospedado

Inicializar um agente hospedado a partir do exemplo de caixa de ferramentas do Foundry, que se conecta a uma caixa de ferramentas via MCP e expõe suas ferramentas ao modelo. Você cria a caixa de ferramentas (my-toolbox) na próxima etapa e aponta o agente para o endpoint dela. Execute esses comandos em um 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/agent.manifest.yaml" --src src/toolbox-agent

Siga as instruções para selecionar seu projeto e uma implantação de modelo existente. Quando você for solicitado a selecionar a alocação de recursos de contêiner, escolha 1 núcleo, memória 2Gi. A imagem de contêiner do agente precisa mais do que a camada padrão. O --src sinalizador configura o agente em src/toolbox-agent.

Etapa 2: Criar a caixa de ferramentas

Crie a caixa de ferramentas e copie o ponto de extremidade MCP retornado. Defina esse ponto de extremidade como uma variável de ambiente em etapas posteriores.

Primeiro, aponte os comandos do toolbox para o projeto Foundry que você selecionou durante a inicialização. Use novamente 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)"

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

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

Etapa 3: Provisionar recursos de Azure

O agente lê o endpoint MCP da caixa de ferramentas da variável de ambiente TOOLBOX_ENDPOINT, que o src/toolbox-agent/agent.yaml resolve a partir do seu ambiente azd. Defina esse valor nas próximas etapas. Provisione os recursos de Azure do agente:

azd provision

Etapa 4: Executar o agente localmente

1. Aponte o agente local para sua toolbox definindo estes valores no arquivo .env em src/toolbox-agent. Cole o ponto de extremidade copiado na Etapa 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 arquivo .env em execuções locais. O exemplo cuida da conexão com a caixa de ferramentas, dos cabeçalhos e da autenticação para você.

2. Inicie o agente:

   azd ai agent run
   

   Esse comando cria um ambiente virtual, instala dependências e atende ao agente em http://localhost:8088. Os pacotes de prévia podem gerar avisos do pip durante a instalação. Esses avisos não bloqueiam.

3. Em um terminal separado, envie prompts que exercitem 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."
   

Etapa 5: Implante no serviço Foundry Agent

Armazene o endpoint copiado na etapa 2 no seu ambiente azd, que é resolvido agent.yaml no momento da implantação. Em seguida, crie e implante o contêiner do agente:

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

Quando o comando for concluído, a saída exibe links para o playground do agente e o endpoint do agente. Invoque o agente implantado:

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

Limpar os recursos

Exclua os recursos quando terminar de usá-los para deixar de gerar cobranças.

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

Solução de problemas

O que você aprendeu

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

• Criou um kit de ferramentas que combina a busca na Web e o servidor MCP do Microsoft Learn em um único endpoint.
• Consumiu o kit de ferramentas de um agente hospedado em Python que se conecta por meio do Protocolo de Contexto do Modelo.
• Executou o agente localmente e o implantou no Serviço do Foundry Agent.

Próxima etapa

Conteúdo relacionado

• O que são agentes hospedados?
• Selecionar uma caixa de ferramentas com base na intenção no Foundry
• Ferramenta de pesquisa na Web
• Conectar agentes a servidores do Model Context Protocol
• Início Rápido: Implantar seu primeiro agente hospedado