Utilize o Foundry Toolbox com a LangChain

Utilize o pacote langchain-azure-ai para carregar ferramentas e capacidades da Foundry Toolbox para os seus agentes LangChain e LangGraph. Uma Foundry Toolbox é um servidor multi-MCP gerido que agrega várias ferramentas configuradas num único endpoint do Model Context Protocol (MCP).

Aprende a carregar ferramentas, identificar ferramentas que precisam de aprovação, carregar competências da caixa de ferramentas como recursos e preparar competências para agentes profundos.

Pré-requisitos

• Uma assinatura do Azure. Crie um gratuitamente.
• Um projeto da Foundry.
• Um modelo de chat implementado (por exemplo, gpt-4.1) no seu projeto.
• Uma caixa de ferramentas configurada no seu projeto Foundry. Tome nota do nome.
• Python 3.10 ou posterior.
• CLI do Azure logado (az login) para que DefaultAzureCredential possa autenticar.

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 competências para agentes deep, instale também deepagents.

Configure o seu ambiente

A caixa de ferramentas precisa de um endpoint do projeto e de um nome da caixa de ferramentas. Forneça-os como argumentos construtores ou através de variáveis de ambiente.

Defina as variáveis do seu 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.

Importa as classes comuns e inicializa o modelo utilizado 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")

Liga-te a uma caixa de ferramentas

Use AzureAIProjectToolbox a partir do namespace langchain_azure_ai.tools para ligar a uma caixa de ferramentas. A integração deteta a ligação ao projeto quando defines a FOUNDRY_PROJECT_ENDPOINT variável de ambiente. O Microsoft Entra ID é o método de autenticação predefinido.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Quando defines as variáveis de ambiente, podes omitir os argumentos do construtor:

toolbox = AzureAIProjectToolbox()

Referência:AzureAIProjectToolbox

Carregar ferramentas a partir de uma caixa de ferramentas

Utilize aget_tools() para abrir uma sessão com o conjunto de ferramentas e carregar todas as ferramentas que este expõe como instâncias de BaseTool do LangChain. Cada chamada é sem estado: abre uma nova sessão MCP, carrega as ferramentas e devolve-as.

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 excerto faz: Liga-se à caixa de ferramentas, carrega as suas ferramentas e liga-as a um agente. Quando invoca o agente, o modelo pode chamar qualquer ferramenta que a toolbox forneça para responder ao pedido.

AzureAIProjectToolbox Também suporta o protocolo gestor de contexto assíncrono. O comportamento é idêntico porque cada chamada aget_tools() gere a respetiva sessão:

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

Referência:create_agent

Identificar ferramentas que necessitem de aprovação

Algumas ferramentas de caixa de ferramentas estão configuradas para exigir aprovação antes de serem executadas. Chama get_tools_requiring_approval() para obter os nomes dessas ferramentas, para poder 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 excerto faz: Inspeciona os metadados da caixa de ferramentas e devolve os nomes das ferramentas cuja configuração define require_approval para always. Utilize esta lista para sujeitar operações sensíveis a um fluxo de aprovação.

Esta capacidade é independente do tratamento do consentimento OAuth. Para mais informações sobre aprovações com intervenção humana, consulte Utilizar o Foundry Agent Service com LangGraph.

Lidar com o consentimento OAuth

O Toolbox no Microsoft Foundry consegue gerir fluxos de trabalho em nome deles. Pode configurar os requisitos de autorização quando adicionar as ferramentas à sua caixa de ferramentas.

Quando uma ferramenta da caixa de ferramentas se conecta a um serviço que ainda não foi autorizado, o gateway do Foundry exige o consentimento OAuth. Em vez de criar uma exceção, get_tools()/aget_tools() devolve uma ferramenta de recurso que mostra o URL de consentimento para que o seu agente possa apresentá-lo ao utilizador.

Quando invoca um agente e o modelo chama a ferramenta de recurso, 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 num navegador para autorizar o acesso e depois reinicie o agente. Depois de conceder o consentimento, a caixa de ferramentas carrega as suas ferramentas normalmente.

Carregue competências a partir de uma caixa de ferramentas

Uma caixa de ferramentas pode expor competências. Uma caixa de ferramentas expõe competências como recursos MCP com URIs do tipo skill://{name}. Uso get_resources() para os carregar como objetos LangChain Blob . Cada Blob contém o nome do recurso na propriedade source e o respetivo URI em 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 excerto faz: Carrega todos skill:// os recursos da caixa de ferramentas como um Blob. O filtro scheme="skills" restringe os resultados a recursos de competências. A correspondência não distingue maiúsculas de minúsculas e aceita a forma singular ou plural ("skill" ou "skills").

Para carregar recursos específicos, passa explicitamente os seus URIs. Quando 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 competências para agentes profundos

Se utilizar o pacote deepagents, chame get_skills() para carregar as competências da caixa de ferramentas como um mapeamento de ficheiros pronto a utilizar para create_deep_agent. Este método baseia-se em get_resources() e elimina o código repetitivo de converter cada Blob na estrutura de ficheiros que os agentes deep esperam.

Instale o pacote:

pip install deepagents

O exemplo seguinte gera a StateBackend (o padrão). Deixe o argumento backend sem definir e passe o mapeamento devolvido como payload de 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 excerto faz: Carrega as competências da caixa de ferramentas num mapeamento de caminhos virtuais SKILL.md e insere-as no estado do agente através do files payload. O agente pode então usar as competências do /skills/ caminho base.

Para inicializar um backend com armazenamento independente, como FilesystemBackend, passe-o como argumento backend. As competências são registadas no back-end, e o mesmo mapeamento é também devolvido:

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 predefinição, os ficheiros de competências são colocados no caminho base /skills/. Indique um(a) base_path diferente para alterar a localização. O valor tem de começar e terminar com uma barra, e transmite o mesmo valor para o argumento skills de create_deep_agent.

Passo seguinte

Conteúdo relacionado

• Utilize o Foundry Agent Service com o LangGraph
• Comece com os SDKs e Endpoints do Microsoft Foundry
• langchain-azure-ai package em PyPI