Use um kit de ferramentas com um agente hospedado

Usar o Microsoft Agent Framework

O exemplo de Python mantido usa FoundryToolbox do pacote de hospedagem do Agent Framework. A classe resolve a caixa de ferramentas direto de TOOLBOX_ENDPOINT ou de FOUNDRY_PROJECT_ENDPOINT e TOOLBOX_NAME. Ela também autentica solicitações MCP e encaminha a ID de chamada por solicitação do runtime hospedado.

Instale o Python 3.12 ou superior, o Azure Developer CLI (azd) 1.25 ou superior e a extensão microsoft.foundry antes de inicializar o exemplo.

1. Inicialize um projeto a partir do exemplo de caixa de ferramentas do agente hospedado:

   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
   

2. Defina o nome da caixa de ferramentas. O exemplo constrói o endpoint do consumidor a partir do endpoint do projeto e do seguinte nome:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Execute o agente localmente:

   azd ai agent run
   

4. Em outro terminal, verifique se o agente descobre as ferramentas da caixa de ferramentas:

   azd ai agent invoke --local "List the tools you can use and briefly describe each one."
   

A resposta lista as ferramentas que a caixa de ferramentas retorna do MCP tools/list. Se a resposta não contiver ferramentas de caixa de ferramentas, consulte Solucionar problemas da conexão.

Usar o LangGraph

Use AzureAIProjectToolbox quando o código do agente hospedado for desenvolvido com LangGraph. A integração carrega as ferramentas da caixa de ferramentas como ferramentas do LangChain e gerencia a autenticação para o ponto de extremidade do consumidor.

1. Instale a integração de Azure do LangChain e suas dependências de hospedagem:

   pip install "langchain-azure-ai[hosting]>=1.2.8"
   

2. Defina FOUNDRY_PROJECT_ENDPOINT no ambiente do agente hospedado. O runtime fornece esse valor após a implantação. Configure você mesmo para desenvolvimento local.

3. Carregue as ferramentas usando o nome da caixa de ferramentas:

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

A saída contém os nomes que a caixa de ferramentas retorna do MCP tools/list:

<tool-name>
<tool-name>

Reference:AzureAIProjectToolbox

1. Passe as ferramentas carregadas para o agente do LangGraph e execute um prompt que exija uma das ferramentas da caixa de ferramentas. Para obter uma implementação completa, consulte o exemplo da caixa de ferramentas LangGraph.

Use a integração de hospedagem do Agent Framework Foundry para registrar uma caixa de ferramentas por nome. AddFoundryToolboxes constrói o endpoint do consumidor a partir de FOUNDRY_PROJECT_ENDPOINT, invoca o MCP tools/list durante a inicialização e adiciona as ferramentas descobertas a cada solicitação do agente.

Instale o SDK do .NET 10 e CLI do Azure antes de executar o exemplo mantido.

1. Comece com o exemplo de caixa de ferramentas hospedada pública ou adicione o pacote de hospedagem do Foundry a um host existente do Agent Framework.

2. Defina essas variáveis de ambiente para desenvolvimento local:

   AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
   AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
   TOOLBOX_NAME=<toolbox-name>
   

   O Foundry fornece FOUNDRY_PROJECT_ENDPOINT para o contêiner implantado. Mantenha o nome da caixa de ferramentas TOOLBOX_NAME; os outros nomes de variáveis FOUNDRY_* são reservados pelo ambiente de execução hospedado.

3. Em Program.cs, registre o agente com AddFoundryResponses e, em seguida, registre a caixa de ferramentas com AddFoundryToolboxes(credential, toolboxName). Depois de criar o aplicativo Web, chame MapFoundryResponses antes Run. O exemplo público inclui os elementos necessários: as importações, os pacotes, a construção do agente e a configuração de credenciais.

4. Inicie o host e, em seguida, chame-o com um prompt que exija uma ferramenta de toolbox. O endpoint /readiness retorna um status não saudável quando o host não consegue enumerar as ferramentas da toolbox.

As integrações da caixa de ferramentas do agente hospedado neste artigo estão disponíveis para Python e .NET. Para chamar o endpoint MCP de outro runtime, use um cliente HTTP MCP com streaming, autentique-se com um token para https://ai.azure.com/.default e implemente o contrato de runtime do agente hospedado.

As integrações da caixa de ferramentas do agente hospedado neste artigo estão disponíveis para Python e .NET. Para chamar o endpoint MCP de outro ambiente de execução, use um cliente HTTP MCP com streaming, se autentique com um token para https://ai.azure.com/.default e implemente o contrato de ambiente de execução do agente hospedado.

Use o Microsoft Foundry Toolkit para Visual Studio Code para estruturar um exemplo de agente hospedado conectado a uma caixa de ferramentas.

Instale o Visual Studio Code, a extensão Microsoft Foundry Toolkit e o pacote de extensões da sua linguagem de programação antes de criar a estrutura do projeto.

1. Na Barra de Atividades, selecione Foundry Toolkit.
2. Em Meus Recursos, expanda seu projeto e expanda Ferramentas.
3. Na guia Caixas de Ferramentas , localize a caixa de ferramentas e selecione Modelo de código scaffold.
4. Na Paleta de Comandos, selecione uma pasta de projeto.
5. Abra o README.md gerado e conclua as etapas de execução local e implantação.
6. Execute um prompt que exija uma ferramenta de caixa de ferramentas e confirme se o agente chama a ferramenta esperada.

Passe o nome da caixa de ferramentas para um exemplo de agente hospedado que constrói o ponto de extremidade do consumidor direto de FOUNDRY_PROJECT_ENDPOINT:

Instale o Azure Developer CLI (azd) versão 1.25 ou posterior e a extensão microsoft.foundry antes de executar estes comandos.

1. Inspecione a caixa de ferramentas e sua versão padrão atual:

   azd ai toolbox show <toolbox-name> --output json
   

   A saída usa a endpoint propriedade. O endpoint retornado por esse comando identifica a versão selecionada e é útil para testar essa versão.

2. Armazene o nome da caixa de ferramentas no ambiente azd:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Para executar o agente hospedado localmente, use:

   azd ai agent run
   

   Em vez disso, para implantar o agente hospedado, use:

   azd deploy
   

Se o aplicativo aceitar apenas uma URL completa, defina TOOLBOX_ENDPOINT como o ponto de extremidade do consumidor sem versão direto de Escolha o ponto de extremidade da caixa de ferramentas.