Utilizzare il Servizio Agente Foundry con LangGraph

Usare il langchain-azure-ai pacchetto per connettere le applicazioni LangGraph e LangChain al servizio agente Foundry. Questo articolo illustra gli scenari pratici, dall'uso di agenti esistenti e dalla composizione di grafici multi-agente a flussi di lavoro abilitati dagli strumenti, approvazioni umane nel processo e tracciamento.

Prerequisiti

• Sottoscrizione Azure. Creane uno gratis.
• Un progetto Fonderia.
• Modello di chat distribuito (ad esempio, gpt-4.1) nel progetto.
• Python 3.10 o versione successiva.
• Interfaccia della riga di comando di Azure connessa (az login) in modo che DefaultAzureCredential possa eseguire l'autenticazione.

Configurare il tuo ambiente

Installare il pacchetto langchain-azure-ai per usare le funzionalità di Microsoft Foundry in LangGraph e LangChain.

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

Impostare le variabili di ambiente usate in questa esercitazione:

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

Uso degli agenti del servizio Foundry Agent

La classe AgentServiceFactory è il punto di partenza per comporre agenti in LangGraph che interagiscono con il servizio agent in Foundry. La factory crea nodi compatibili con LangGraph che vengono eseguiti tramite il servizio Agent e che possono essere usati per comporre soluzioni più complesse con LangGraph.

Creare la factory dell'agente connettendo la classe AgentServiceFactory a un progetto Foundry. Tutti gli agenti creati o a cui si fa riferimento tramite questa factory vengono gestiti all'interno del progetto e visibili nel portale foundry (nuovo).

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(),
)	

Usare un agente esistente

Si consiglia di creare e configurare agenti nel portale di Foundry o nel Foundry SDK e quindi farvi riferimento per nome con get_agent_node per comporre grafici. Questo approccio è consigliato perché mantiene centralizzata la configurazione dell'agente in Foundry e consente al codice di concentrarsi sull'orchestrazione. È anche possibile creare agenti a livello di codice con create_prompt_agent quando è necessario definire completamente gli agenti nel codice.

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

Cosa fa questo frammento di codice: Recupera un riferimento a un agente Foundry esistente come nodo compatibile con LangGraph. L'agente deve esistere già nel progetto Foundry. Usare version="latest" per impostare sempre come destinazione la versione più recente o aggiungere un numero di versione specifico per la stabilità.

Verificare che l'agente possa eseguire:

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

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

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

Goodbye, world!

Conversazioni e stato

I nodi collegati al servizio agente tengono automaticamente traccia delle risposte nelle conversazioni. La azure_ai_agents_conversation_id proprietà viene aggiunta allo stato in modo da poter fare riferimento o continuare conversazioni:

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

azure_ai_agents_conversation_id: <conversation-id>

Comporre grafici con agenti esistenti

È possibile usare i nodi del servizio Agent esattamente come qualsiasi altro nodo in LangGraph per creare grafici complessi. Nell'esempio seguente viene compilato un grafico di routing condizionale in cui un utente locale router_node esamina il messaggio utente e decide se delegare a un 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()

Cosa fa questo frammento di codice: Compila un langgraph StateGraph con due nodi. router_node controlla l'ultimo messaggio, se contiene "nega", delega a expert_node (l'agente Foundry recuperato con get_agent_node). In caso contrario, il router gestisce la richiesta in locale e termina il grafico. Questo modello illustra come combinare la logica locale con gli agenti Foundry.

Il grafico è simile al seguente:

Richiamare il grafico:

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!

In Test 1 il router gestisce la richiesta in locale. In Test 2 il router delega all'agente Foundry, che risponde con l'opposto dell'istruzione dell'utente.

Creare un agente prompt di base

Quando è necessario definire interamente gli agenti nel codice, ad esempio durante la creazione di prototipi o quando la configurazione dell'agente deve essere attiva insieme all'applicazione, usare create_prompt_agent. Iniziare con un agente prompt in stile ReAct minimo per verificare l'integrazione.

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'}

Attivare l'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!

Cosa fa questo frammento di codice: Crea un agente basato su prompt nel servizio agente Foundry e restituisce un langgraph CompiledStateGraph che lo usa. L'agente è immediatamente visibile nel portale Foundry in Agenti. La get_agents_id_from_graph chiamata recupera l'ID agente assegnato a Foundry in modo da poter tenere traccia o fare riferimento all'agente in un secondo momento.

È possibile visualizzare il modo in cui l'agente è stato creato e usato all'interno del grafico LangGraph stampando la relativa rappresentazione diagramma. Il nodo foundryAgent viene eseguito nel Servizio Agente Fonderia. Si noti che il nome e la versione dell'agente sono visibili nel grafico.

from IPython import display

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

factory.delete_agent(agent)

Aggiungi strumenti all'agente

È possibile aggiungere strumenti all'agente per eseguire azioni. Il metodo create_prompt_agent implementa il ciclo dell'agente per te.

È necessario distinguere due tipi di strumenti:

• Strumenti locali: sono strumenti che vengono eseguiti nello stesso luogo in cui è in esecuzione il codice dell'agente. Possono essere funzioni chiamabili o qualsiasi funzione disponibile per l'ecosistema LangChain/LangGraph.
• Strumenti predefiniti: si tratta di strumenti che possono essere eseguiti esclusivamente nel servizio agente Foundry; lato server. Gli strumenti lato server possono essere applicati solo agli agenti Foundry.

L'aggiunta di strumenti locali all'agente aggiunge un nodo dello strumento al grafico per l'esecuzione di tali strumenti. Gli strumenti predefiniti non aggiungono un nodo dello strumento e vengono eseguiti nel servizio quando si effettua una richiesta.

La sezione seguente illustra come usare entrambi:

Aggiungere strumenti locali

È possibile definire funzioni Python locali e collegarle come strumenti. Questo modello è utile per le operazioni di utilità e logica di business deterministiche.

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

Passa gli strumenti alla create_prompt_agent funzione e invoca l'agente con un problema aritmetico in più passaggi.

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.

Cosa fa questo frammento di codice: Crea un agente con tre strumenti aritmetici. Quando l'agente determina una chiamata allo strumento necessaria, il servizio agente Foundry orchestra la chiamata allo strumento in locale e invia il risultato all'agente per continuare a ragionare.

Usare altri strumenti dell'ecosistema LangGraph/LangChain, ad esempio Azure Document Intelligence in Strumenti Fonderia dallo stesso flusso dell'agente. Anche se questi strumenti sono connessi a una risorsa Foundry, non sono esclusivi del servizio agent e quindi agiscono come uno strumento locale.

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()],
)

Chiedere all'agente di analizzare una fattura da un 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**.

Cosa fa questo frammento di codice: Chiede all'agente di estrarre dati da un'immagine di fattura di esempio. L'agente chiama AzureAIDocumentIntelligenceTool per analizzare il documento e restituisce il risultato. Output previsto: "L'importo totale nella fattura è $144,00".

Aggiungere strumenti predefiniti

Gli strumenti predefiniti nel servizio Foundry Agent eseguono il lato server anziché in un nodo degli strumenti come gli strumenti locali. Gli strumenti nello spazio dei nomi langchain_azure_ai.agents.prebuilt.tools.* sono tutti strumenti predefiniti e funzionano solo con create_prompt_agent.

Esempio: usare lo strumento dell'interprete di codice

Creare un agente dell'interprete di codice per l'analisi dei dati e richiamarlo con un file di dati fittizio data.csv .

Prima di eseguire questo esempio, creare un file locale data.csv nella directory di lavoro corrente.

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=='}
]

Esempio: uso dello strumento di generazione di immagini

L'esempio seguente illustra come usare ImageGenTool per la generazione di immagini:

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

Uso di altri strumenti predefiniti

Qualsiasi strumento del servizio Agente Foundry può essere usato con create_prompt_agent. Usare AgentServiceBaseTool per avvolgere gli strumenti dall'SDK di Azure AI Projects e allegarli all'agente per i prompt.

Prima di eseguire questo esempio, verificare che l'ID dell'archivio vettoriale esista nel progetto.

Nell'esempio seguente viene illustrato come usare un oggetto 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"]),
		)
	],
)

Human-in-the-Loop

Alcuni strumenti in Foundry hanno flussi di lavoro di approvazione predefiniti, ad esempio MCPTool. È possibile richiedere l'approvazione prima che le invocazioni del tool vengano eseguite per un tool specifico nel server.

Il metodo create_prompt_agent implementa lo stesso modello consigliato da LangGraph, introducendo un nodo di approvazione nel grafico:

L'esempio seguente illustra come usare MCPTool con l'approvazione:

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"}

Inviare l'approvazione usando un Command in 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, ...

Observability

Quando si compongono soluzioni usando il servizio Foundry Agent e LangGraph, alcune parti vengono eseguite nel servizio Agent mentre altre vengono eseguite in cui viene eseguito il codice.

La classe AzureAIOpenTelemetryTracer consente di tracciare soluzioni end-to-end compilate con LangGraph usando lo standard OpenTelemetry, supportato dal servizio Agent.

Per tracciare il codice, usare:

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] })

Che questo frammento di codice fa: Crea un'istanza di AzureAIOpenTelemetryTracer per inviare tracce a Azure Application Insights usando lo standard OpenTelemetry. Imposta il parametro agent_id per identificare le tracce impostando la proprietà gen_ai.agent.id in intervalli di tipo agent_invoke. AzureAIOpenTelemetryTracer richiede un connection string per Azure Application Insights. In questo caso, non viene visualizzato perché è stata impostata la variabile di ambiente AZURE_AI_PROJECT_ENDPOINT, che la classe può usare per rilevare il connection string al Azure Application Insights associato al progetto. È possibile passare qualsiasi stringa di connessione necessaria.

Per visualizzare le tracce, è importante comprendere che sono presenti due agenti qui:

1. L'agente Foundry, che costituisce il back-end di uno dei nodi del grafico.
2. L'intero grafo LangGraph, composto da molti nodi.

È possibile visualizzare le tracce dell'agente Foundry usando il portale Foundry, ma per visualizzare la traccia dell'agente LangGraph durante lo sviluppo, è necessario usare Azure Monitor nel portale Azure.

Per visualizzare le tracce usando Azure Monitor:

1. Passare al portale Azure.

2. Passare alla risorsa Azure Application Insights configurata.

3. Usando la barra di navigazione a sinistra, selezionare Analizza>Agenti (Anteprima).

4. Viene visualizzato un dashboard che mostra gli agenti, i modelli e le esecuzioni degli strumenti. Usare questa visualizzazione per comprendere l'immagine generale degli agenti.

5. Selezionare Visualizzare le tracce con le esecuzioni degli agenti. Il pannello laterale mostra tutte le tracce generate dalle esecuzioni dell'agente.

   Screenshot che mostra la sezione Agents (Preview) in Azure Monitor che visualizza più esecuzioni.

6. Selezionare una delle tracce. Verranno visualizzati i dettagli.

   

7. Si noti che due agenti sono coinvolti nella conversazione: l'agente foundryAgent e quello denominato mcp-github-specs-agent-langgraph.

Pulire gli agenti

Eliminare gli agenti creati negli esempi per evitare di lasciare le risorse inutilizzate.

Eliminare solo gli agenti creati nella sessione.

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)

Risoluzione dei problemi

Usare questo elenco di controllo per diagnosticare i problemi comuni quando si usa langchain-azure-ai con il servizio Agent.

Abilita registrazione diagnostica

Attivare prima i log di debug in modo da poter esaminare i dettagli di autenticazione, flusso di richiesta e esecuzione degli strumenti.

import logging

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

Se hai bisogno di più dettagli, aumenta il logging per includere altre librerie:

import logging

logging.basicConfig(level=logging.DEBUG)

Convalidare la configurazione in anticipo

• Verificare che AZURE_AI_PROJECT_ENDPOINT punti all'endpoint del progetto corretto e che sia in uso un progetto Fonderia nella nuova esperienza.
• Verificare che MODEL_DEPLOYMENT_NAME corrisponda a un modello distribuito esistente.
• Verificare il contesto di autenticazione con az account show.
• Usare prima un esempio minimo create_prompt_agent .

Verificare l'accesso alle risorse e alle autorizzazioni

• Assicurati che il tuo account abbia accesso al progetto Foundry e alla distribuzione del modello.
• Verificare che le dipendenze downstream (ad esempio, gli archivi vettoriali o le risorse degli strumenti) esistano e siano raggiungibili.
• Se uno strumento richiede un tipo di risorsa specifico, verificare che venga effettuato il provisioning della risorsa nella sottoscrizione e nell'area corrette.

Contenuti correlati

• Introduzione agli SDK e agli endpoint di Microsoft Foundry
• Configurare le integrazioni di traccia per i framework agente
• Introduzione rapida al servizio di Foundry Agent
• pacchetto langchain-azure-ai su PyPI