Use uma caixa de ferramentas com um agente hospedado

Utilize o Microsoft Agent Framework

O exemplo de Python mantido utiliza FoundryToolbox do pacote de alojamento do Agent Framework. A classe resolve a caixa de ferramentas a partir de TOOLBOX_ENDPOINT, ou a partir de FOUNDRY_PROJECT_ENDPOINT e TOOLBOX_NAME. Também autentica os pedidos MCP e encaminha o ID de chamada por pedido do ambiente de execução alojado.

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

1. Inicialize um projeto a partir do exemplo da 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. Define o nome da caixa de ferramentas. O exemplo cria o endpoint do consumidor a partir do endpoint do projeto e deste nome:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Execute o agente localmente:

   azd ai agent run
   

4. Noutro 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 devolve do MCP tools/list. Se a resposta não contiver ferramentas da caixa de ferramentas, consulte Resolver problemas de ligação.

Use LangGraph

Use AzureAIProjectToolbox quando o seu código de agente hospedado for construído com o LangGraph. A integração carrega as ferramentas da caixa de ferramentas como ferramentas LangChain e gere a autenticação no endpoint do consumidor.

1. Instale a integração com o LangChain Azure e as suas dependências de alojamento:

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

2. Defina FOUNDRY_PROJECT_ENDPOINT no ambiente do agente alojado. O tempo de execução fornece este valor após a implantação. Configure-o você mesmo para desenvolvimento local.

3. Carregue as ferramentas pelo 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 devolve do MCP tools/list:

<tool-name>
<tool-name>

Referência:AzureAIProjectToolbox

1. Passe as ferramentas carregadas ao seu agente LangGraph e execute um prompt que requer uma das ferramentas da caixa de ferramentas. Para uma implementação completa, consulte o exemplo da caixa de ferramentas LangGraph.

Utilize a integração de alojamento do Agent Framework Foundry para registar uma toolbox pelo respetivo nome. AddFoundryToolboxes constrói o endpoint do consumidor a partir de FOUNDRY_PROJECT_ENDPOINT, chama o MCP tools/list durante a inicialização e adiciona as ferramentas descobertas a cada pedido de agente.

Instala o SDK .NET 10 e o CLI do Azure antes de executares o sample mantido.

1. Comece pelo exemplo da caixa de ferramentas hospedada publicamente, ou adicione o pacote de alojamento Foundry a um host existente do Agent Framework.

2. Defina estas variáveis ambientais para o 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>
   

   Foundry fornece FOUNDRY_PROJECT_ENDPOINT ao contentor implementado. Mantenha o nome da caixa de ferramentas em TOOLBOX_NAME; os outros nomes de variáveis em FOUNDRY_* estão reservados pelo ambiente de execução alojado.

3. Em Program.cs, regista o agente com AddFoundryResponses, e depois regista a caixa de ferramentas com AddFoundryToolboxes(credential, toolboxName). Depois de criar a aplicação web, chame MapFoundryResponses antes de Run. O exemplo público inclui as importações necessárias, os pacotes, a criação do agente e a configuração das credenciais.

4. Inicie o host e, em seguida, invoque-o com um pedido que requeira uma ferramenta da caixa de ferramentas. O /readiness endpoint devolve um estado pouco saudável quando o host não consegue enumerar as ferramentas da caixa de ferramentas.

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

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

Utilize o Microsoft Foundry Toolkit for Visual Studio Code para criar a estrutura de um exemplo de agente alojado ligado a uma caixa de ferramentas.

Instale o Visual Studio Code, a extensão do 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. Na secção Meus Recursos, expanda o seu projeto e depois expanda as Ferramentas.
3. No separador Caixas de Ferramentas, localize a caixa de ferramentas e, em seguida, selecione Modelo de código Scaffold.
4. Na Paleta de Comandos, selecione uma pasta de projeto.
5. Abra o ficheiro gerado README.md e, em seguida, conclua os passos de execução local e de implementação correspondentes.
6. Execute um prompt que exija uma ferramenta da caixa de ferramentas e confirme que o agente invoca a ferramenta esperada.

Passe o nome da caixa de ferramentas para um exemplo de agente hospedado que constrói o endpoint do consumidor a partir de FOUNDRY_PROJECT_ENDPOINT:

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

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

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

   A saída utiliza a endpoint propriedade. O endpoint devolvido por este 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, utilize:

   azd ai agent run
   

   Para implementar o agente hospedado, utilize:

   azd deploy
   

Se a sua aplicação aceitar apenas um URL completo, defina TOOLBOX_ENDPOINT como o endpoint do consumidor não versionado na secção Escolher o endpoint da toolbox.