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. Defina o ponto de extremidade como uma variável de ambiente e passe o nome da caixa de ferramentas para o construtor.

Defina o ponto de extremidade do projeto:

import os

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

A integração usa FOUNDRY_PROJECT_ENDPOINT ou AZURE_AI_PROJECT_ENDPOINT para o endpoint do projeto. Nenhuma variável de ambiente fornece o nome da caixa de ferramentas, portanto, sempre passe toolbox_name para o construtor.

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

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

O kit de ferramentas se autentica com DefaultAzureCredential, que detecta sua sessão do az login. Você não precisa construir uma credencial por conta própria.

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 o ponto de extremidade no ambiente, você pode omitir project_endpoint. Você sempre precisa fornecer toolbox_name:

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")

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 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: A 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

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