Utiliser le service de l’agent Foundry avec LangGraph

Utilisez le langchain-azure-ai package pour connecter les applications LangGraph et LangChain au service De l’agent Foundry. Cet article décrit des scénarios pratiques, de l’utilisation d’agents existants et de la composition de graphiques multi-agents aux flux de travail assistés par des outils, les approbations avec intervention humaine et le suivi.

Conditions préalables

• Un abonnement Azure. Créez-en un gratuitement.
• Un projet Foundry.
• Modèle de chat déployé (par exemple, gpt-4.1) dans votre projet.
• Python 3.10 ou version ultérieure.
• Azure CLI connecté (az login) afin que DefaultAzureCredential puisse s’authentifier.

Configurer votre environnement

Installez le package langchain-azure-ai pour utiliser les fonctionnalités Microsoft Foundry dans LangGraph et LangChain.

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

Définissez vos variables d’environnement que nous utilisons dans ce tutoriel :

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

Utilisation des agents du service d'agent Foundry

La classe AgentServiceFactory est votre point de départ pour composer des agents dans LangGraph qui interagissent avec le service d’agent dans Foundry. L'usine crée des nœuds compatibles LangGraph qui s’exécutent via le service d’agent et qui peuvent être utilisés pour composer des solutions plus complexes avec LangGraph.

Créez la fabrique d’agent en connectant la AgentServiceFactory classe à un projet Foundry. Tous les agents que vous créez ou référencez via cette fabrique sont gérés dans le projet et visibles dans le portail Foundry (nouveau).

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

Utiliser un agent existant

Nous vous recommandons de créer et de configurer des agents dans le portail Foundry ou le Kit de développement logiciel (SDK) Foundry, puis de les référencer par nom get_agent_node pour composer des graphiques. Cette approche est recommandée, car elle conserve la configuration de l’agent centralisée dans Foundry et permet à votre code de se concentrer sur l’orchestration. Vous pouvez également créer des agents par programmation create_prompt_agent lorsque vous devez définir des agents entièrement dans le code.

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

Ce que fait cet extrait de code : Récupère une référence à un agent Foundry existant en tant que nœud compatible LangGraph. L’agent doit déjà exister dans votre projet Foundry. Permet version="latest" de cibler toujours la version la plus récente ou d’épingler un numéro de version spécifique pour la stabilité.

Testez que votre agent peut exécuter :

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

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

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

Goodbye, world!

Conversations et état

Les nœuds attachés au service d’agent effectuent automatiquement le suivi des réponses dans les conversations. La propriété azure_ai_agents_conversation_id est intégrée à l’état afin de pouvoir s’y référer ou prolonger les échanges :

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

azure_ai_agents_conversation_id: <conversation-id>

Composer des graphiques avec des agents existants

Vous pouvez utiliser des nœuds de service agent comme n’importe quel autre nœud de LangGraph pour créer des graphiques complexes. L’exemple suivant génère un graphique de routage conditionnel où un local router_node inspecte le message utilisateur et décide s’il faut déléguer à un agent 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()

Ce que fait cet extrait de code : Génère un LangGraph StateGraph avec deux nœuds. router_node examine le dernier message ; s’il contient « negate », il redirige vers expert_node (l’agent Foundry obtenu via get_agent_node). Sinon, le routeur gère la requête localement et termine le graphique. Ce modèle montre comment combiner une logique locale avec des agents Foundry.

Le graphique se présente comme suit :

Appelez le graphique :

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!

Dans le test 1, le routeur gère la requête localement. Dans le test 2, le routeur délègue à l’agent Foundry, qui répond avec l’opposé de l’instruction de l’utilisateur.

Créer un agent d’invite simple

Lorsque vous devez définir des agents entièrement dans du code ( par exemple, lors du prototypage ou lorsque la configuration de l’agent doit fonctionner en même temps que votre application) utilisez create_prompt_agent. Commencez par un agent d’invite de style ReAct minimal pour vérifier votre intégration.

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

Appelez l’agent :

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!

Ce que fait cet extrait : crée un agent basé sur des invites dans le service Foundry Agent Service et renvoie un LangGraph CompiledStateGraph qui l’utilise. L’agent est immédiatement visible dans votre portail Foundry sous Agents. L’appel get_agents_id_from_graph récupère l’ID de l’agent affecté à Foundry afin que vous puissiez suivre ou référencer l’agent ultérieurement.

Vous pouvez visualiser la façon dont l’agent a été créé et utilisé dans le graphique LangGraph en imprimant sa représentation de diagramme. Le nœud foundryAgent s’exécute dans le service Foundry Agent. Notez comment le nom et la version de l’agent sont visibles dans le graphique.

from IPython import display

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

factory.delete_agent(agent)

Ajouter des outils à votre agent

Vous pouvez ajouter des outils à votre agent pour effectuer des actions. La méthode create_prompt_agent implémente la boucle de l’agent pour vous.

Vous devez distinguer deux types d’outils :

• Outils locaux : il s’agit d’outils qui s’exécutent à l'endroit où votre code d’agent s’exécute. Ils peuvent être des fonctions appelantes ou n’importe quelle fonction disponible pour l’écosystème LangChain/LangGraph.
• Outils intégrés : il s’agit d’outils qui peuvent s’exécuter exclusivement dans le service De l’agent Foundry ; côté serveur. Les outils côté serveur ne peuvent être appliqués qu’aux agents Foundry.

L’ajout d’outils locaux à votre agent ajoute un nœud d’outil à votre graphique pour que ces outils s’exécutent. Les outils intégrés n’ajoutent pas de nœud d’outil et sont exécutés dans le service lorsque vous effectuez une demande.

La section suivante explique comment utiliser les deux :

Ajouter des outils locaux

Vous pouvez définir des fonctions de Python locales et les attacher en tant qu’outils. Ce modèle est utile pour les opérations de logique métier et d’utilitaire déterministes.

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

Transmettez les outils à la create_prompt_agent fonction et appelez l’agent avec un problème arithmétique à plusieurs étapes :

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.

Ce que fait cet extrait de code : Crée un agent avec trois outils arithmétiques. Lorsque l’agent détermine qu’un appel d’outil est nécessaire, le Service Agent Foundry orchestre l’appel d’outil localement et retourne le résultat à l’agent pour poursuivre le raisonnement.

Utilisez d’autres outils de l’écosystème LangGraph/LangChain comme Azure Document Intelligence dans Foundry Tools à partir du même flux d’agent. Bien que ces outils soient connectés à une ressource Foundry, ils ne sont pas exclusifs au service d’agent et agissent donc comme un outil 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()],
)

Demandez à l’agent d’analyser une facture à partir d’une 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**.

Ce que fait cet extrait de code : Demande à l’agent d’extraire des données d’un exemple d’image de facture. L’agent appelle AzureAIDocumentIntelligenceTool pour analyser le document et retourne le résultat. Sortie attendue : « Le montant total de la facture est de 144,00 $. »

Ajouter des outils intégrés

Les outils intégrés du service Foundry Agent exécutent côté serveur au lieu d’un nœud d’outil comme les outils locaux. Les outils de l’espace de noms langchain_azure_ai.agents.prebuilt.tools.* sont tous des outils intégrés et fonctionnent uniquement avec create_prompt_agent.

Exemple : utiliser l’outil interpréteur de code

Créez un agent d’interpréteur de code pour l’analyse des données et appelez-le avec un fichier de données fictif data.csv .

Avant d’exécuter cet exemple, créez un fichier local data.csv dans votre répertoire de travail actuel.

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

Exemple : utilisation de l’outil de génération d’images

L’exemple suivant montre comment utiliser ImageGenTool pour la génération d’images :

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

Utilisation d’autres outils intégrés

Tout outil de service de l’agent Foundry peut être utilisé avec create_prompt_agent. Utilisez AgentServiceBaseTool pour intégrer les outils à partir du SDK Azure AI Projects et les attacher à votre agent de requête.

Avant d’exécuter cet exemple, vérifiez que l’ID de magasin de vecteurs existe dans votre projet.

L’exemple suivant montre comment utiliser un 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"]),
		)
	],
)

Intervention humaine

Certains outils de Foundry ont des flux de travail d’approbation intégrés, tels que MCPTool. Vous pouvez exiger l’approbation avant que les appels d’outils s’exécutent pour un outil donné sur le serveur.

La méthode create_prompt_agent implémente le même modèle recommandé par LangGraph, en introduisant un nœud d’approbation dans le graphique :

L’exemple suivant montre comment utiliser MCPTool avec approbation :

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

Envoyez l’approbation à l’aide d’un Command dans 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, ...

Observabilité

Lorsque vous composez des solutions à l’aide du Service Agent Foundry et de LangGraph, certains éléments s’exécutent dans le Service Agent, tandis que d’autres s'exécutent là où votre code s'exécute.

La classe AzureAIOpenTelemetryTracer vous permet de suivre les solutions de bout en bout créées avec LangGraph à l’aide de la norme OpenTelemetry, qui est prise en charge par le service Agent.

Pour suivre votre code, utilisez :

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

Quoi fait : Crée une instance de AzureAIOpenTelemetryTracer pour envoyer des traces à Azure Application Insights à l’aide de la norme OpenTelemetry. Il définit le paramètre agent_id pour identifier les traces en définissant la propriété gen_ai.agent.id dans des étendues de type agent_invoke. AzureAIOpenTelemetryTracer nécessite un chaîne de connexion pour Azure Application Insights. Dans ce cas, il n'est pas affiché, car vous définissez la variable d'environnement AZURE_AI_PROJECT_ENDPOINT, que la classe peut utiliser pour détecter la chaîne de connexion à Azure Application Insights associée au projet. Vous pouvez passer n’importe quelle chaîne de connexion dont vous avez besoin.

Pour afficher les traces, il est important de comprendre qu’il existe deux agents ici :

1. L’agent Foundry, qui constitue le backend de l’un des nœuds du graphe.
2. Le graphique LangGraph dans son ensemble, qui est composé de plusieurs nœuds.

Vous pouvez afficher les traces de l’agent Foundry à l’aide du portail Foundry mais pour afficher la trace de l’agent LangGraph lors du développement, vous devez utiliser Azure Monitor dans le portail Azure.

Pour afficher les traces à l’aide de Azure Monitor :

1. Accédez au portail Azure.

2. Accédez au Azure Application Insights que vous avez configuré.

3. À l’aide de la barre de navigation de gauche, sélectionnez Examiner>Agents (préversion).

4. Vous voyez un tableau de bord montrant des agents, des modèles et des exécutions d’outils. Utilisez cette vue pour comprendre l’image générale de vos agents.

5. Sélectionnez Afficher les traces avec les exécutions d’agent. Le panneau latéral affiche toutes les traces générées par les exécutions de l’agent.

   

6. Sélectionnez l’une des traces. Vous devriez voir les détails.

   

7. Notez comment deux agents sont impliqués dans la conversation : l’agent foundryAgent et celui nommé mcp-github-specs-agent-langgraph.

Nettoyer les agents

Supprimez les agents que vous avez créés dans des exemples pour éviter de laisser des ressources inutilisées.

Supprimez uniquement les agents que vous avez créés dans votre session.

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)

Dépannage

Utilisez cette liste de contrôle pour diagnostiquer les problèmes courants lors de l’utilisation langchain-azure-ai du service Agent.

Activer la journalisation des diagnostics

Activez d’abord les journaux de débogage pour vous permettre d’inspecter les détails de l’authentification, du flux de requête et de l’exécution des outils.

import logging

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

Si vous avez besoin de plus de détails, augmentez la journalisation pour inclure d’autres bibliothèques :

import logging

logging.basicConfig(level=logging.DEBUG)

Valider la configuration tôt

• Assurez-vous que AZURE_AI_PROJECT_ENDPOINT indique le bon point de terminaison du projet et que vous utilisez un projet Foundry avec la nouvelle interface.
• Confirmez que MODEL_DEPLOYMENT_NAME correspond à un modèle déployé existant.
• Vérifiez le contexte d’authentification avec az account show.
• Utilisez d’abord un exemple minimal create_prompt_agent .

Vérifier l’accès aux ressources et aux autorisations

• Assurez-vous que votre compte a accès au projet Foundry et au déploiement du modèle.
• Vérifiez que les dépendances en aval (par exemple, les magasins vectoriels ou les ressources d’outil) existent et sont accessibles.
• Si un outil nécessite un type de ressource spécifique, vérifiez que la ressource est provisionnée dans l’abonnement et la région appropriés.

Contenu connexe

• Commencez avec les SDKs de Microsoft Foundry et points-de-terminaison
• Configurer des intégrations de suivi pour les infrastructures d’agent
• Démarrage rapide du service Foundry Agent
• package langchain-azure-ai sur PyPI