Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 queDefaultAzureCredentialpossa 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.