Usar o Foundry Toolbox com LangChain

Use o pacote langchain-azure-ai para carregar ferramentas e habilidades de um Foundry Toolbox em seus agentes LangChain e LangGraph. Um Foundry Toolbox é um servidor multi-MCP gerenciado que agrega várias ferramentas configuradas em um único endpoint do Model Context Protocol (MCP).

Você vai aprender a carregar ferramentas, identificar ferramentas que exigem aprovação, carregar habilidades da caixa de ferramentas como recursos e preparar habilidades para agentes avançados.

Pré-requisitos

• Uma assinatura do Azure. Criar um gratuitamente.
• Um projeto do Foundry.
• Um modelo de chat implantado (por exemplo, gpt-4.1) em seu projeto.
• Uma caixa de ferramentas configurada em seu projeto do Foundry. Anote seu nome.
• Python 3.10 ou posterior.
• CLI do Azure está conectado (az login) para que DefaultAzureCredential possa autenticar-se.

Instale os pacotes necessários:

pip install -U langchain-azure-ai langchain-mcp-adapters httpx azure-identity

A integração da caixa de ferramentas requer langchain-mcp-adapters e httpx. Para carregar habilidades para agentes avançados, instale deepagents também.

Configurar seu ambiente

A caixa de ferramentas precisa de um ponto de extremidade do projeto e de um nome para a caixa de ferramentas. Forneça-os como argumentos de construtor ou por meio de variáveis de ambiente.

Defina suas variáveis de ambiente:

import os

# Project endpoint (recommended)
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
    "https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Name of the toolbox configured in your Foundry project
os.environ["FOUNDRY_AGENT_TOOLBOX_NAME"] = "<your-toolbox-name>"

A integração também aceita a variável de ambiente FOUNDRY_PROJECT_ENDPOINT como alternativa para o endpoint do projeto.

Importe as classes comuns e inicialize o modelo usado ao longo deste artigo:

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1")

Conectar-se a uma caixa de ferramentas

Use AzureAIProjectToolbox no namespace langchain_azure_ai.tools para se conectar a uma caixa de ferramentas. A integração detecta a conexão do projeto quando você define a variável de FOUNDRY_PROJECT_ENDPOINT ambiente. Microsoft Entra ID é o método de autenticação padrão.

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    toolbox_name="my-toolbox",
)

Ao definir as variáveis de ambiente, você pode omitir os argumentos do construtor:

toolbox = AzureAIProjectToolbox()

Reference:AzureAIProjectToolbox

Carregar ferramentas da caixa de ferramentas

Chame aget_tools() para abrir uma sessão com a caixa de ferramentas e carregar todas as ferramentas expostas como instâncias BaseTool do LangChain. Cada chamada é sem estado: ela abre uma nova sessão MCP, carrega as ferramentas e as retorna.

async def main():
    toolbox = AzureAIProjectToolbox(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        toolbox_name="my-toolbox",
    )

    tools = await toolbox.aget_tools()

    agent = create_agent(model=model, tools=tools)

    result = await agent.ainvoke(
        {"messages": [HumanMessage("What can you do?")]}
    )
    print(result["messages"][-1].content)

O que este snippet de código faz: Conecta-se à caixa de ferramentas, carrega suas ferramentas e as associa a um agente. Quando você invoca o agente, o modelo pode chamar qualquer ferramenta que a caixa de ferramentas fornece para atender à solicitação.

AzureAIProjectToolbox também dá suporte ao protocolo assíncrono do gerenciador de contexto. O comportamento é idêntico porque cada aget_tools() chamada gerencia sua própria sessão:

async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
    tools = await toolbox.aget_tools()

Reference:create_agent

Identificar ferramentas que exigem aprovação

Algumas ferramentas de caixa de ferramentas são configuradas para exigir aprovação antes de serem executadas. Chame get_tools_requiring_approval() para recuperar os nomes dessas ferramentas, para que você possa adicionar uma etapa de intervenção humana antes da execução.

tools_needing_approval = await toolbox.get_tools_requiring_approval()

print("Tools that require approval before execution:")
for name in tools_needing_approval:
    print(f"- {name}")

O que este trecho de código faz: Inspeciona os metadados da toolbox e retorna os nomes das ferramentas cuja configuração define require_approval como always. Use essa lista para bloquear operações confidenciais por trás de um fluxo de trabalho de aprovação.

Essa funcionalidade é independente do tratamento de consentimento do OAuth. Para obter mais informações sobre aprovações com intervenção humana, consulte Usar o Serviço de Agente do Foundry com LangGraph.

Lidar com o consentimento do OAuth

A caixa de ferramentas do Microsoft Foundry dá suporte a fluxos de trabalho on-behalf-of. Você pode configurar os requisitos de autorização ao adicionar as ferramentas à sua caixa de ferramentas.

Quando uma ferramenta de caixa de ferramentas se conecta a um serviço que ainda não foi autorizado, o gateway do Foundry requer consentimento do OAuth. Em vez de gerar uma exceção, get_tools()/aget_tools() retorna uma ferramenta de fallback que apresenta a URL de consentimento para que o agente possa apresentá-la ao usuário.

Quando você invoca um agente e o modelo chama a ferramenta de fallback, a resposta contém uma mensagem semelhante à seguinte:

OAuth consent is required before this toolbox can be used. Open the following
URL in a browser to authorize access, then restart the agent:

  https://consent.azure-apim.net/...

Abra a URL em um navegador para autorizar o acesso e reinicie o agente. Depois de conceder consentimento, a caixa de ferramentas carrega suas ferramentas normalmente.

Carregar habilidades na caixa de ferramentas

Uma caixa de ferramentas pode expor habilidades. Uma caixa de ferramentas expõe habilidades como recursos MCP com URIs no formato skill://{name}. Use get_resources() para carregá-los como objetos Blob LangChain. Cada Blob carrega o nome do recurso na propriedade source e o URI bruto em metadata["uri"].

skill_blobs = toolbox.get_resources(scheme="skills")

for blob in skill_blobs:
    print(f"Skill: {blob.source}")
    print(blob.as_string())

Skill: jokes-teller/SKILL.md
{'content': '---\nname: jokes-teller\ndescription: An skill to tell jokes\n---\n\nUse...'}

O que este trecho faz: Carrega, como um skill://, todos os recursos Blob da toolbox. O filtro scheme="skills" restringe os resultados a recursos de competências. A correspondência não diferencia maiúsculas de minúsculas e aceita a forma singular ou plural ("skill" ou "skills").

Para carregar recursos específicos, passe suas URIs explicitamente. Quando você fornece uris, o scheme filtro é ignorado:

skill_blobs = toolbox.get_resources(uris="skill://my-skill/SKILL.md")

Use aget_resources() para o equivalente assíncrono:

skill_blobs = await toolbox.aget_resources(scheme="skills")

Carregar habilidades para agentes avançados

Se você usar o pacote deepagents, chame get_skills() para carregar habilidades da caixa de ferramentas como um mapeamento de arquivos pronto para uso para create_deep_agent. Esse método se baseia em get_resources() e elimina o trabalho repetitivo de converter cada Blob na estrutura de arquivos que os agentes deep esperam.

Instale o pacote:

pip install deepagents

O exemplo a seguir propaga um StateBackend (o padrão). Deixe o argumento backend sem definir e passe o mapeamento retornado como payload files em invoke:

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_files = toolbox.get_skills()

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=StateBackend(),
    skills=["/skills/"],
)

agent.invoke({"messages": [HumanMessage("Use a skill")], "files": skill_files})

O que este trecho de código faz: carrega as habilidades da caixa de ferramentas em um mapeamento de caminhos SKILL.md virtuais e as insere no estado do agente por meio do payload files. Em seguida, o agente pode usar as habilidades sob o caminho base /skills/.

Para inicializar um backend com armazenamento independente, como FilesystemBackend, passe-o como argumento backend. As habilidades são gravadas no back-end, e o mesmo mapeamento também é retornado:

from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(root_dir="./my-project")
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
await toolbox.aget_skills(backend=backend)

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=backend,
    skills=["/skills/"],
)

Por padrão, os arquivos de habilidade são armazenados sob o caminho base /skills/. Passe um base_path diferente para mudar a localização. O valor deve começar e terminar com uma barra, e você passa o mesmo valor para o argumento skills de create_deep_agent.

Próxima etapa

Usar o Serviço de Agente do Foundry com o LangGraph

Conteúdo relacionado

• Usar o Serviço de Agente do Foundry com o LangGraph
• Comece com os SDKs e endpoints do Microsoft Foundry
• pacote langchain-azure-ai no PyPI