Agents Hébergés Azure du Framework d'Agents
Construisez des agents persistants sur Azure AI Foundry en utilisant le SDK Python Microsoft Agent Framework.
Architecture
Requête Utilisateur → AzureAIAgentsProvider → Service Agent Azure AI (Persistant)
↓
Agent.run() / Agent.run_stream()
↓
Outils : Fonctions | Hébergés (Code/Recherche/Web) | MCP
↓
AgentThread (persistance de la conversation)
Installation
# Framework complet (recommandé)
pip install agent-framework --pre
# Ou uniquement le package spécifique Azure
pip install agent-framework-azure-ai --pre
Variables d'Environnement
export AZURE_AI_PROJECT_ENDPOINT="https://<projet>.services.ai.azure.com/api/projects/<id-projet>" # Requis pour toutes les méthodes d'authentification
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" # Requis pour toutes les méthodes d'authentification
export BING_CONNECTION_ID="votre-id-connexion-bing" # Pour la recherche web
export AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production
Authentification & Cycle de Vie
🔑 Deux règles s'appliquent à chaque exemple de code ci-dessous :
- Privilégiez
DefaultAzureCredential. Il fonctionne localement (Azure CLI / VS Code / Developer CLI) et dans Azure (identité managée, identité de charge de travail) sans changement de code. Évitez les chaînes de connexion, les clés de compte/API — elles contournent l'audit et la rotation Entra.
- Développement local :
DefaultAzureCredentialfonctionne tel quel.- Production : définissez
AZURE_TOKEN_CREDENTIALS=prod(ouAZURE_TOKEN_CREDENTIALS=<credential_spécifique>) pour limiter la chaîne de credentials aux credentials sécurisés pour la production.- Enveloppez chaque client dans un gestionnaire de contexte afin que les transports HTTP, les sockets et les caches de jetons soient libérés de manière déterministe :
- Synchrone :
with <Client>(...) as client:- Asynchrone :
async with <Client>(...) as client:etasync with DefaultAzureCredential() as credential:(depuisazure.identity.aio)Les extraits de code peuvent abréger cette configuration, mais le code de production doit toujours suivre les deux règles.
from azure.identity.aio import AzureCliCredential, DefaultAzureCredential, ManagedIdentityCredential
# Développement
credential = AzureCliCredential()
# Production
# Développement local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_spécifique>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utiliser un credential spécifique directement en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
Workflow de Base
Agent Simple
import asyncio
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="MonAgent",
instructions="Vous êtes un assistant utile.",
)
result = await agent.run("Bonjour !")
print(result.text)
asyncio.run(main())
Agent avec Outils de Fonction
from typing import Annotated
from pydantic import Field
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def obtenir_meteo(
lieu: Annotated[str, Field(description="Nom de la ville pour obtenir la météo")],
) -> str:
"""Obtenir la météo actuelle pour un lieu."""
return f"Météo à {lieu} : 72°F, ensoleillé"
def obtenir_heure_actuelle() -> str:
"""Obtenir l'heure UTC actuelle."""
from datetime import datetime, timezone
return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AgentMeteo",
instructions="Vous aidez avec les requêtes météo et d'heure.",
tools=[obtenir_meteo, obtenir_heure_actuelle], # Passer les fonctions directement
)
result = await agent.run("Quel temps fait-il à Seattle ?")
print(result.text)
Agent avec Outils Hébergés
from agent_framework import (
HostedCodeInterpreterTool,
HostedFileSearchTool,
HostedWebSearchTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AgentMultiOutils",
instructions="Vous pouvez exécuter du code, rechercher des fichiers et rechercher sur le web.",
tools=[
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
],
)
result = await agent.run("Calcule la factorielle de 20 en Python")
print(result.text)
Réponses en Streaming
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AgentStreaming",
instructions="Vous êtes un assistant utile.",
)
print("Agent : ", end="", flush=True)
async for chunk in agent.run_stream("Raconte-moi une courte histoire"):
if chunk.text:
print(chunk.text, end="", flush=True)
print()
Fils de Conversation
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AgentDialogue",
instructions="Vous êtes un assistant utile.",
tools=[obtenir_meteo],
)
# Créer un fil pour la persistance de la conversation
thread = agent.get_new_thread()
# Premier tour
result1 = await agent.run("Quel temps fait-il à Seattle ?", thread=thread)
print(f"Agent : {result1.text}")
# Deuxième tour - le contexte est conservé
result2 = await agent.run("Et à Portland ?", thread=thread)
print(f"Agent : {result2.text}")
# Sauvegarder l'ID du fil pour une reprise ultérieure
print(f"ID de conversation : {thread.conversation_id}")
Sorties Structurées
from pydantic import BaseModel, ConfigDict
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
class ReponseMeteo(BaseModel):
model_config = ConfigDict(extra="forbid")
localisation: str
temperature: float
unite: str
conditions: str
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AgentStructure",
instructions="Fournissez des informations météorologiques au format structuré.",
response_format=ReponseMeteo,
)
result = await agent.run("Météo à Seattle ?")
meteo = ReponseMeteo.model_validate_json(result.text)
print(f"{meteo.localisation} : {meteo.temperature}°{meteo.unite}")
Méthodes du Fournisseur
| Méthode | Description |
|---|---|
create_agent() | Créer un nouvel agent sur le service Azure AI |
get_agent(agent_id) | Récupérer un agent existant par son ID |
as_agent(sdk_agent) | Envelopper un objet Agent du SDK (pas d'appel HTTP) |
Référence Rapide des Outils Hébergés
| Outil | Import | Objectif |
|---|---|---|
HostedCodeInterpreterTool | from agent_framework import HostedCodeInterpreterTool | Exécuter du code Python |
HostedFileSearchTool | from agent_framework import HostedFileSearchTool | Rechercher dans les magasins de vecteurs |
HostedWebSearchTool | from agent_framework import HostedWebSearchTool | Recherche web Bing |
HostedMCPTool | from agent_framework import HostedMCPTool | MCP géré par le service |
MCPStreamableHTTPTool | from agent_framework import MCPStreamableHTTPTool | MCP géré par le client |
Exemple Complet
import asyncio
from typing import Annotated
from pydantic import BaseModel, Field
from agent_framework import (
HostedCodeInterpreterTool,
HostedWebSearchTool,
MCPStreamableHTTPTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def obtenir_meteo(
lieu: Annotated[str, Field(description="Nom de la ville")],
) -> str:
"""Obtenir la météo pour un lieu."""
return f"Météo à {lieu} : 72°F, ensoleillé"
class ResultatAnalyse(BaseModel):
resume: str
constats_cles: list[str]
confiance: float
async def main():
async with (
AzureCliCredential() as credential,
MCPStreamableHTTPTool(
name="Docs MCP",
url="https://learn.microsoft.com/api/mcp",
) as outil_mcp,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="AssistantRecherche",
instructions="Vous êtes un assistant de recherche avec plusieurs capacités.",
tools=[
obtenir_meteo,
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
outil_mcp,
],
)
fil = agent.get_new_thread()
# Non-streaming
resultat = await agent.run(
"Recherche les meilleures pratiques Python et résume-moi",
thread=fil,
)
print(f"Réponse : {resultat.text}")
# Streaming
print("\nStreaming : ", end="")
async for morceau in agent.run_stream("Continue avec des exemples", thread=fil):
if morceau.text:
print(morceau.text, end="", flush=True)
print()
# Sortie structurée
resultat = await agent.run(
"Analyse les résultats",
thread=fil,
response_format=ResultatAnalyse,
)
analyse = ResultatAnalyse.model_validate_json(resultat.text)
print(f"\nConfiance : {analyse.confiance}")
if __name__ == "__main__":
asyncio.run(main())
Conventions
- Utilisez toujours les gestionnaires de contexte asynchrones :
async with provider: - Passez les fonctions directement au paramètre
tools=(converties automatiquement en AIFunction) - Utilisez
Annotated[type, Field(description=...)]pour les paramètres de fonction - Utilisez
get_new_thread()pour les conversations à plusieurs tours - Préférez
HostedMCPToolpour le MCP géré par le service,MCPStreamableHTTPToolpour le MCP géré par le client
Bonnes Pratiques
- Ce SDK est async-first — utilisez des gestionnaires
async defetasync withpartout. - Utilisez toujours des gestionnaires de contexte pour les clients et les credentials asynchrones. Enveloppez chaque client dans
with Client(...) as client:(synchrone) ouasync with Client(...) as client:(asynchrone). PourDefaultAzureCredentialasynchrone depuisazure.identity.aio, utilisez égalementasync with credential:afin que les jetons et les transports soient nettoyés.
Fichiers de Référence
- references/tools.md : Modèles détaillés d'outils hébergés
- references/mcp.md : Intégration MCP (hébergé + local)
- references/threads.md : Gestion des fils et des conversations
- references/advanced.md : OpenAPI, citations, sorties structurées