Use o Serviço de Agente da Fundição com o LangGraph

Use o langchain-azure-ai pacote para ligar aplicações LangGraph e LangChain ao Foundry Agent Service. Este artigo aborda cenários práticos, desde a utilização de agentes existentes e a composição de redes multiagente até fluxos de trabalho automatizados por ferramentas, aprovações com intervenção humana e rastreamento.

Pré-requisitos

• Uma subscrição do Azure. Crie um gratuitamente.
• Um projeto da Foundry.
• Um modelo de chat implementado (por exemplo, gpt-4.1) no seu projeto.
• Python 3.10 ou posterior.
• CLI do Azure iniciado sessão (az login) para que DefaultAzureCredential possa autenticar-se.

Configure o seu ambiente

Instale o pacote langchain-azure-ai para utilizar as capacidades Microsoft Foundry no LangGraph e LangChain.

pip install langchain-azure-ai[tools,opentelemetry] azure-identity

Defina as variáveis de ambiente que usamos neste tutorial:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export MODEL_DEPLOYMENT_NAME="gpt-4.1"

Utilização de agentes do Foundry Agent Service

A classe AgentServiceFactory é o seu ponto de partida para compor agentes no LangGraph que interagem com o Serviço de Agentes no Foundry. A fábrica cria nós compatíveis com LangGraph que passam pelo Agent Service e que podem ser usados para compor soluções mais complexas com o LangGraph.

Crie a fábrica de agentes ligando a AgentServiceFactory classe a um projeto Foundry. Todos os agentes que crias ou referencias através desta fábrica são geridos dentro do projeto e visíveis no portal Foundry (novo).

import os

from langchain_core.messages import HumanMessage

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents import AgentServiceFactory
from langchain_azure_ai.utils.agents import pretty_print

factory = AgentServiceFactory(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
)	

Use um agente existente

Recomendamos criar e configurar agentes no portal Foundry ou no SDK Foundry e depois referiá-los pelo nome com get_agent_node para compor grafos. Esta abordagem é recomendada porque mantém a configuração dos agentes centralizada na Foundry e permite que o seu código se concentre na orquestração. Também podes criar agentes programaticamente com create_prompt_agent quando precisas de definir agentes inteiramente em código.

echo_node = factory.get_agent_node(
	name="my-echo-agent",
	version="latest",
)

O que este excerto faz: Recupera uma referência a um agente Foundry existente como um nó compatível com LangGraph. O agente já deve existir no seu projeto Foundry. Use version="latest" para sempre direcionar a versão mais recente, ou fixar um número de versão específico para maior estabilidade.

Teste se o seu agente consegue executar:

response = echo_node.invoke(
	{"messages": [HumanMessage(content="Hello, world!")]}
)
pretty_print(response)

================================ Human Message =================================

Hello, world!
================================== Ai Message ==================================
Name: my-echo-agent

Goodbye, world!

Conversas e estado

Os nós ligados ao Serviço de Agente registam automaticamente as respostas nas conversas. A azure_ai_agents_conversation_id propriedade é adicionada ao estado para que possa consultar ou continuar as conversas:

print(
	"azure_ai_agents_conversation_id:",
	response["azure_ai_agents_conversation_id"],
)

azure_ai_agents_conversation_id: <conversation-id>

Construir diagramas com agentes existentes

Pode usar nós do Serviço de Agente, assim como qualquer outro nó no LangGraph, para construir grafos complexos. O exemplo seguinte constrói um grafo de encaminhamento condicional onde um local router_node inspeciona a mensagem do utilizador e decide se delega a um agente Foundry.

from typing import Literal
from langchain_core.messages import AIMessage
from langgraph.graph import StateGraph, MessagesState, START, END


class RouterState(MessagesState):
	jump_to: str | None


def router_node(state: RouterState):
	last_message = state["messages"][-1].content.lower()

	# Simple logic simulating a model decision
	if "negate" in last_message:
		return RouterState(
			messages=state["messages"], jump_to="delegate"
		)
	else:
		return RouterState(
			messages=[AIMessage(content="I can handle this!")],
			jump_to=None,
		)


def route_decision(state: RouterState) -> Literal["expert_node", END]:
	if state.get("jump_to", None) == "delegate":
		return "expert_node"
	return END


workflow = StateGraph(RouterState)

workflow.add_node("router_node", router_node)
workflow.add_node("expert_node", echo_node)
workflow.add_edge(START, "router_node")
workflow.add_conditional_edges("router_node", route_decision)
workflow.add_edge("expert_node", END)

app = workflow.compile()

O que este excerto faz: Constrói um LangGraph StateGraph com dois nós. Inspeciona router_node a última mensagem — se contiver "negar", delega ao expert_node (o agente da Foundry recuperado com get_agent_node). Caso contrário, o router trata o pedido localmente e termina o grafo. Este padrão demonstra como combinar lógica local com agentes Foundry.

O gráfico é o seguinte:

Invocar o grafo:

print("--- Test 1 (Direct) ---")
pretty_print(
	app.invoke({"messages": [HumanMessage(content="Hello, world!")]})
)

print("\n--- Test 2 (Delegated) ---")
pretty_print(
	app.invoke(
		{"messages": [HumanMessage(content="Negate that I'm a genius!")]}
	)
)

------------------------------- Test 1 (Direct) --------------------------------
================================ Human Message =================================

Hello, world!
================================== Ai Message ==================================

I can handle this!

------------------------------ Test 2 (Delegated) ------------------------------
================================ Human Message =================================

Negate that I'm a genius!
================================== Ai Message ==================================
Name: my-echo-agent

You're not a genius!

No Teste 1, o roteador trata o pedido a nível local. No Teste 2, o roteador delega ao agente Foundry, que responde com o oposto da afirmação do utilizador.

Crie um agente básico de prompts

Quando precisar de definir agentes inteiramente em código — por exemplo, durante a prototipagem ou quando a configuração do agente deve conviver com a sua aplicação — use create_prompt_agent. Comece com um agente de prompts mínimo ao estilo ReAct para verificar a sua integração.

agent = factory.create_prompt_agent(
	name="my-echo-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are a helpful AI assistant that always replies with the "
		"opposite of what the user says."
	),
)

print(f"Agent created with ID: {factory.get_agents_id_from_graph(agent)}")

Agent created with ID: {'my-echo-agent:1'}

Invocar o agente:

messages = [HumanMessage(content="I'm a genius and I love programming!")]
response = agent.invoke({"messages": messages})
pretty_print(response)

================================ Human Message =================================

I'm a genius and I love programming!
================================== Ai Message ==================================
Name: my-echo-agent

You are not a genius and you hate programming!

O que este excerto faz: Cria um agente baseado em prompts no Foundry Agent Service e devolve um LangGraph CompiledStateGraph que o utiliza. O agente é imediatamente visível no portal da Foundry em Agentes. A get_agents_id_from_graph chamada recupera o ID do agente atribuído pela Foundry para que possas rastrear ou referenciar o agente mais tarde.

Pode visualizar como o agente foi criado e usado dentro do grafo LangGraph imprimindo a sua representação em diagrama. O nó foundryAgent funciona no Serviço de Agentes da Fundição. Repara como o nome e a versão do agente são visíveis no gráfico.

from IPython import display

display.Image(agent.get_graph().draw_mermaid_png())

factory.delete_agent(agent)

Equipe o seu agente com ferramentas

Pode adicionar ferramentas ao seu agente para realizar ações. O método create_prompt_agent implementa o ciclo agente para ti.

Deves distinguir dois tipos de ferramentas:

• Ferramentas locais: Ferramentas que são executadas no mesmo local onde o código do seu agente está a ser executado. Podem ser funções chamáveis ou qualquer função disponível para o ecossistema LangChain/LangGraph.
• Ferramentas integradas: São ferramentas que podem funcionar exclusivamente no Foundry Agent Service; do lado do servidor. As ferramentas do lado do servidor só podem ser aplicadas a agentes Foundry.

Adicionar ferramentas locais ao seu agente adiciona um nó de ferramenta ao seu grafo para essas ferramentas serem executadas. As ferramentas integradas não adicionam um nó de ferramenta e são executadas no serviço quando faz um pedido.

A secção seguinte explica como usar ambos:

Adicionar ferramentas locais

Podes definir funções locais em Python e associá-las como ferramentas. Este padrão é útil para lógica de negócio determinística e operações de utilidade.

def add(a: int, b: int) -> int:
	"""Add two integers."""
	return a + b


def multiply(a: int, b: int) -> int:
	"""Multiply two integers."""
	return a * b


def divide(a: int, b: int) -> float:
	"""Divide one integer by another."""
	return a / b

Passe as ferramentas para a create_prompt_agent função e depois invoque o agente com um problema aritmético de múltiplos passos.

math_agent = factory.create_prompt_agent(
	name="math-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are a helpful assistant tasked with performing arithmetic "
		"on a set of inputs."
	),
	tools=[add, multiply, divide],
)

messages = [
	HumanMessage(
		content="Add 3 and 4. Multiply the output by 2. Divide the output by 5."
	)
]
response = math_agent.invoke({"messages": messages})
pretty_print(response)

================================ Human Message =================================

Add 3 and 4. Multiply the output by 2. Divide the output by 5
================================== Ai Message ==================================
Tool Calls:
  add (call_JSmltOCbsTRkbNEBMAVSgVe1)
 Call ID: call_JSmltOCbsTRkbNEBMAVSgVe1
  Args:
    a: 3
    b: 4
================================= Tool Message =================================
Name: add

7
================================== Ai Message ==================================
Tool Calls:
  multiply (call_ae6M6XyhOIBOkPy3ETd8nDI9)
...
================================== Ai Message ==================================
Name: math-agent

Here's the step-by-step calculation:
1. Add 3 and 4 to get 7.
2. Multiply the result (7) by 2 to get 14.
3. Divide the result (14) by 5 to get 2.8.

The final result is 2.8.

O que este excerto faz: Cria um agente com três ferramentas aritméticas. Quando o agente determina que é necessária uma chamada de ferramenta, o Serviço de Agentes da Fundição orquestra localmente a invocação da ferramenta e envia o resultado de volta ao agente para continuidade do raciocínio.

Use outras ferramentas do ecossistema LangGraph/LangChain, como o Azure Document Intelligence no Foundry Tools, do mesmo fluxo de agentes. Embora essas ferramentas estejam ligadas a um recurso da Foundry, não são exclusivas do Serviço de Agente e, por isso, funcionam como uma ferramenta local.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_parser_agent = factory.create_prompt_agent(
	name="document-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions="You are a helpful assistant tasked with analyzing documents.",
	tools=[AzureAIDocumentIntelligenceTool()],
)

Peça ao agente para analisar uma fatura a partir de uma URL:

messages = [
	HumanMessage(
		content=(
			"What's the total amount in the invoice at "
			"https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/"
			"sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/"
			"forms/Form_1.jpg"
		)
	)
]
response = document_parser_agent.invoke({"messages": messages})
pretty_print(response)

================================ Human Message =================================

What's the total amount in ...
================================== Ai Message ==================================
Tool Calls:
  azure_ai_document_intelligence (call_32V6bqeCcJhhsOXDrYFXggnc)
 Call ID: call_32V6bqeCcJhhsOXDrYFXggnc
  Args:
    source_type: url
    source: https://raw.githubusercontent.com/Azure/ ...
================================= Tool Message =================================
Name: azure_ai_document_intelligence

Content: Purchase Order Hero ...
================================== Ai Message ==================================
Name: document-agent

The total amount in the invoice is **$144.00**.

O que este excerto faz: Pede ao agente que extraia dados de uma imagem de fatura de exemplo. O agente liga AzureAIDocumentIntelligenceTool para analisar o documento e devolve o resultado. Resultado esperado: "O montante total na fatura é de $144,00."

Adicionar ferramentas integradas

As ferramentas integradas no Foundry Agent Service funcionam do lado do servidor em vez de num nó de ferramentas como as ferramentas locais. As ferramentas no namespace langchain_azure_ai.agents.prebuilt.tools.* são todas ferramentas incorporadas e só funcionam com create_prompt_agent.

Exemplo: usar a ferramenta de interpretação de código

Crie um agente interpretador de código para análise de dados e invoque-o com um ficheiro de dados fictício data.csv .

Antes de executar este exemplo, crie um ficheiro local data.csv no seu diretório de trabalho atual.

import base64
from langchain_azure_ai.agents.prebuilt.tools import CodeInterpreterTool

code_interpreter_agent = factory.create_prompt_agent(
	name="code-interpreter-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are a data analyst agent. Analyze CSV data and create "
		"visualizations when helpful."
	),
	tools=[CodeInterpreterTool()],
)

with open("data.csv", "rb") as file_handle:
	csv_data = base64.b64encode(file_handle.read()).decode()

response = code_interpreter_agent.invoke(
	{
		"messages": [
			HumanMessage(
				content=[
					{
						"type": "file",
						"mime_type": "text/csv",
						"base64": csv_data,
					},
					{
						"type": "text",
						"text": (
							"Create a pie chart showing sales by region and "
							"return it as a PNG image."
						),
					},
				]
			)
		]
	}
)
pretty_print(response)

================================ Human Message =================================

[
	{'type': 'file', 'mime_type': 'text/csv', 'base64': '77u/bW9udG...xTb3V0aAo='}, 
	{'type': 'text', 'text': 'create a pie chart with the data showing sales by region and show it to me as a png image.'}
]
================================== Ai Message ==================================
Name: code-interpreter-agent

[
	{'type': 'text', 'text': 'Here is the pie chart showing sales by region as a PNG image:\n\n[Download the Pie Chart](sandbox:/mnt/data/sales_by_region_pie.png)'}, 
	{'type': 'image', 'mime_type': 'image/png', 'base64': 'iVBORw0...ErkJggg=='}
]

Exemplo: usar a ferramenta de geração de imagens

O exemplo seguinte mostra como usar ImageGenTool para geração de imagens:

from langchain_azure_ai.agents.prebuilt.tools import ImageGenTool

image_agent = factory.create_prompt_agent(
	name="image-generator-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are an image generation assistant. You receive a text prompt and "
		"must generate an image by using the configured tool."
	),
	tools=[ImageGenTool(model_deployment="gpt-image-1.5", quality="medium")],
)

response = image_agent.invoke(
	{"messages": [HumanMessage("Generate an image of a sunset over mountains.")]}
)
pretty_print(response)

================================ Human Message =================================

Generate an image of a sunset over the mountains.
================================== Ai Message ==================================
Name: image-generator-agent

Utilização de outras ferramentas incorporadas

Qualquer ferramenta para serviço de agente de fundição pode ser usada com create_prompt_agent. Use AgentServiceBaseTool para encapsular ferramentas do SDK de Projetos de IA da Azure e anexá-las ao seu agente de prompts.

Antes de executar esta amostra, certifique-se de que o ID da loja vetorial existe no seu projeto.

O exemplo seguinte mostra como usar um FileSearchTool:

from azure.ai.projects.models import FileSearchTool
from langchain_azure_ai.agents.prebuilt.tools import AgentServiceBaseTool

file_search_agent = factory.create_prompt_agent(
	name="file-search-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are a helpful agent with access to a file search tool over a "
		"vector store."
	),
	tools=[
		AgentServiceBaseTool(
			tool=FileSearchTool(vector_store_ids=["vector-store-1"]),
		)
	],
)

Humano no ciclo

Certas ferramentas no Foundry têm fluxos de trabalho de aprovação incorporados, como MCPTool. Pode exigir aprovação antes de as chamadas de ferramenta serem executadas para uma determinada ferramenta no servidor.

O método create_prompt_agent implementa o mesmo padrão recomendado pelo LangGraph, introduzindo um nó de aprovação no grafo:

O exemplo seguinte mostra como usar MCPTool com aprovação:

from langchain_azure_ai.agents.prebuilt.tools import MCPTool
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command

mcp_agent = factory.create_prompt_agent(
	name="mcp-github-specs-agent",
	model=os.environ["MODEL_DEPLOYMENT_NAME"],
	instructions=(
		"You are a helpful agent that can use MCP tools to assist users."
	),
	tools=[
		MCPTool(
			server_label="api-specs",
			server_url="https://gitmcp.io/Azure/azure-rest-api-specs",
			require_approval="always",
		)
	],
	checkpointer=MemorySaver(),
)

config = {"configurable": {"thread_id": "mcp-session-1"}}

response = mcp_agent.invoke(
	input={"messages": [HumanMessage("What APIs are available for Azure Cosmos DB?")]},
	config=config,
)
pretty_print(response)

================================ Human Message =================================

What APIs are available for Azure Cosmos DB?
================================== Ai Message ==================================
Tool Calls:
  mcp_approval_request (mcpr_74e314080483acce0069a11d2d9f008190a971212ac61d76d8)
 Call ID: mcpr_74e314080483acce0069a11d2d9f008190a971212ac61d76d8
  Args:
    server_label: api-specs
    name: search_azure_rest_api_docs
    arguments: {"query":"Cosmos DB APIs"}

================================== Interrupt ==================================
Interrupt ID: c3cb23363f91d097298fb3c6f8fbf70a
Interrupt Value:
  Tool Call ID: mcpr_74e314080483acce0069a11d2d9f008190a971212ac61d76d8
  Server Label: api-specs
  Tool Name: search_azure_rest_api_docs
  Arguments: {"query":"Cosmos DB APIs"}

Envie a aprovação usando um Command no LangGraph:

response = mcp_agent.invoke(Command(resume={"approve": True}), config)

pretty_print(response)

================================ Human Message =================================

What APIs are available for Azure Cosmos DB?
================================== Ai Message ==================================
Tool Calls:
  mcp_approval_request (mcpr_74e314080483acce0069a11d2d9f008190a971212ac61d76d8)
 Call ID: mcpr_74e314080483acce0069a11d2d9f008190a971212ac61d76d8
  Args:
    server_label: api-specs
    name: search_azure_rest_api_docs
    arguments: {"query":"Cosmos DB APIs"}
================================= Tool Message =================================

{"approve": true}
================================== Ai Message ==================================
Name: mcp-github-specs-agent

Azure Cosmos DB supports multiple APIs, ...

Observabilidade

Quando compões soluções usando o Foundry Agent Service e o LangGraph, certas partes correm no Agent Service enquanto outras correm onde o teu código é executado.

A classe AzureAIOpenTelemetryTracer permite rastrear soluções de ponta a ponta construídas com LangGraph usando o padrão OpenTelemetry, que é suportado pelo Agent Service.

Para rastrear o seu código, utilize:

from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

tracer = AzureAIOpenTelemetryTracer(
    agent_id="mcp-github-specs-agent-langgraph"
)

mcp_agent = mcp_agent.with_config({ "callbacks": [tracer] })

O que este excerto faz: Cria uma instância de AzureAIOpenTelemetryTracer para enviar traços para Aplicação Azure Insights usando o padrão OpenTelemetry. Defina o parâmetro agent_id para identificar rastros definindo a propriedade gen_ai.agent.id em intervalos do tipo agent_invoke. AzureAIOpenTelemetryTracer requer um cadeia de ligação para Aplicação Azure Insights. Neste caso, não é mostrado porque definiste a variável de ambiente AZURE_AI_PROJECT_ENDPOINT, que a classe pode usar para detetar a cadeia de conexão ao Aplicação Azure Insights associado ao projeto. Podes passar qualquer cadeia de ligação que precises.

Para visualizar os rastos, é importante perceber que existem dois agentes aqui:

1. O agente Foundry, que atua como backend de um dos nós do grafo.
2. Todo o grafo LangGraph completo, que é composto por vários nós.

Pode visualizar os traços do agente Foundry usando o portal Foundry, mas para visualizar o rastreio do agente LangGraph durante o desenvolvimento, precisa de usar Azure Monitor no portal Azure.

Para visualizar os rastros usando o Azure Monitor:

1. Vai ao portal Azure.

2. Navegue até ao Aplicação Azure Insights que configurou.

3. Usando a barra de navegação da esquerda, selecione Investigar>Agentes (Pré-visualização).

4. Vês um painel que mostra agentes, modelos e execuções de ferramentas. Use esta perspetiva para compreender a situação geral dos seus agentes.

5. Selecione Ver Rastreios com Execuções de Agente. O painel lateral mostra todos os rastreios gerados pelas execuções dos agentes.

   

6. Selecione um dos traços. Deves ver os detalhes.

   

7. Repare como dois agentes estão envolvidos na conversa: o agente foundryAgent e o que se chama mcp-github-specs-agent-langgraph.

Agentes de limpeza

Elimina agentes que criaste em samples para evitar deixar recursos por usar.

Apague apenas os agentes que criou na sua sessão.

factory.delete_agent(math_agent)	
factory.delete_agent(document_parser_agent)
factory.delete_agent(image_agent)
factory.delete_agent(code_interpreter_agent)
factory.delete_agent(mcp_agent)
factory.delete_agent(file_search_agent)

Resolução de problemas

Utilize esta lista de verificação para diagnosticar problemas comuns ao utilizar langchain-azure-ai o Serviço de Agente.

Ativar registo de diagnóstico

Ativa primeiro os registos de depuração para poderes inspecionar a autenticação, o fluxo de pedidos e os detalhes de execução da ferramenta.

import logging

logging.getLogger("langchain_azure_ai").setLevel(logging.DEBUG)

Se precisar de mais detalhes, aumente o registo para incluir outras bibliotecas:

import logging

logging.basicConfig(level=logging.DEBUG)

Validar a configuração cedo

• Confirma que AZURE_AI_PROJECT_ENDPOINT aponta para o endpoint correto do projeto e que estás a utilizar um projeto Foundry com a nova experiência.
• Confirme MODEL_DEPLOYMENT_NAME que corresponde a um modelo já implementado.
• Verifique o contexto de autenticação com az account show.
• Use primeiro um exemplo mínimo create_prompt_agent .

Verificar acesso a recursos e permissões

• Garanta que a sua conta tem acesso ao projeto e à implementação do modelo Foundry.
• Garantir que as dependências a jusante (como repositórios vetoriais ou recursos de ferramentas) existam e sejam acessíveis.
• Se uma ferramenta requer um tipo específico de recurso, verifique se esse recurso está provisionado na subscrição e região corretas.

Conteúdo relacionado

• Comece a usar os SDKs e Endpoints Microsoft Foundry
• Configurar integrações de rastreamento para frameworks de agentes
• Serviço de Agente de Fundição Quickstart
• langchain-azure-ai package em PyPI