Partage via

Concevez à l’aide d’agents, de conversations et de réponses

Le service Microsoft Foundry Agent utilise trois composants d’exécution principaux ( agents, conversations et réponses) pour alimenter les interactions avec état et multitours. Un agent définit le modèle, les instructions et les outils à utiliser. Une conversation se poursuit avec son historique à travers les différents tours de discussion. Une réponse est la sortie produite par l’agent lorsqu’il traite l’entrée.

Cet article décrit chaque composant et explique comment les utiliser ensemble dans le code. Vous allez apprendre à créer un agent, démarrer une conversation, générer des réponses (avec ou sans agent), ajouter des messages de suivi et diffuser en continu des résultats, avec des exemples en Python, C#, JavaScript, JavaScript et l’API REST.

Fonctionnement des composants runtime

Lorsque vous travaillez avec un agent, vous suivez un modèle cohérent :

  • Créer un agent : définissez un agent pour commencer à envoyer des messages et recevoir des réponses.
  • Créer une conversation (facultative) : utilisez une conversation pour conserver l’historique à travers les tours. Si vous n’utilisez pas de conversation, transférez le contexte à l’aide de la sortie d’une réponse précédente.
  • Générez une réponse : l’agent traite les éléments d’entrée dans la conversation et toutes les instructions fournies dans la demande. L’agent peut ajouter des éléments à la conversation.
  • Vérifier l’état de la réponse : surveillez la réponse jusqu’à ce qu’elle se termine (en particulier en mode streaming ou en mode arrière-plan).
  • Récupérez la réponse : affichez la réponse générée à l’utilisateur.

Le diagramme suivant illustre l’interaction de ces composants dans une loop d’agent classique.

Diagramme qui montre la boucle d'exécution de l’agent : une définition de l’agent et un historique facultatif des conversations pour la génération de réponses, qui peut appeler des outils, réintégrer des éléments dans la conversation et produire des éléments de sortie que vous affichez à l’utilisateur.

Vous fournissez une entrée utilisateur (et éventuellement l’historique des conversations), le service génère une réponse (y compris les appels d’outils en cas de configuration) et les éléments résultants peuvent être réutilisés en tant que contexte pour le tour suivant.

Prerequisites

Pour exécuter les exemples de cet article, vous avez besoin des éléments suivants :

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

Créer un agent

Un agent est une définition d’orchestration persistante qui combine des modèles IA, des instructions, du code, des outils, des paramètres et des contrôles de sécurité ou de gouvernance facultatifs.

Stockez les agents sous la forme de ressources nommées et avec version dans Microsoft Foundry. Pendant la génération de réponse, la définition de l’agent fonctionne avec l’historique des interactions (conversation ou réponse précédente) pour traiter et répondre à l’entrée utilisateur.

L’exemple suivant crée un agent de saisie avec un nom, un modèle et des instructions. Utilisez le client de projet pour la création et le contrôle de version de l’agent.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Note

Les agents sont maintenant identifiés à l’aide du nom de l’agent et de la version de l’agent. Ils n’ont plus de GUID appelé AgentID .

Pour obtenir des types d’agents supplémentaires (workflow, hébergés), consultez le cycle de vie du développement d’un agent.

Créer un agent avec des outils

Les outils étendent ce qu’un agent peut faire au-delà de la génération de texte. Lorsque vous attachez des outils à un agent, l’agent peut appeler des services externes, exécuter du code, rechercher des fichiers et accéder aux sources de données pendant la génération de réponse, à l’aide d’outils tels que la recherche web ou l’appel de fonction.

Vous pouvez attacher un ou plusieurs outils lorsque vous créez un agent. Pendant la génération de réponse, l’agent décide s’il faut appeler un outil en fonction de l’entrée de l’utilisateur et de ses instructions. L’exemple suivant crée un agent avec un outil de recherche web attaché.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Pour obtenir la liste complète des outils disponibles, consultez la vue d’ensemble des outils. Pour connaître les meilleures pratiques, consultez Les meilleures pratiques pour l’utilisation d’outils.

Générer des réponses

La génération de réponses appelle l’agent. L’agent utilise sa configuration et tout historique fourni (conversation ou réponse précédente) pour effectuer des tâches en appelant des modèles et des outils. Dans le cadre de la génération de réponse, l’agent ajoute des éléments à la conversation.

Vous pouvez également générer une réponse sans définir d’agent. Dans ce cas, vous fournissez toutes les configurations directement dans la demande et les utilisez uniquement pour cette réponse. Cette approche est utile pour les scénarios simples avec des outils minimaux.

De plus, vous pouvez bifurquer la conversation à partir de l’identifiant de la première réponse ou de celui de la deuxième réponse

Générer une réponse avec un agent

L’exemple suivant génère une réponse à l’aide d’une référence d’agent, puis envoie une question de suivi à l’aide de la réponse précédente en tant que contexte.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

Lorsqu’un agent utilise des outils pendant la génération de réponse, la sortie de la réponse contient des éléments d’appel d’outil en même temps que le message final. Vous pouvez effectuer une response.output itération pour inspecter chaque élément et afficher les appels d’outils( tels que les recherches web, les appels de fonction ou les recherches de fichiers) avant d’imprimer la réponse texte.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

Générer une réponse sans stocker

Par défaut, le service stocke l'historique des réponses côté serveur, vous permettant ainsi de consulter previous_response_id pour le contexte multitour. Si vous définissez store sur false, le service ne conserve pas de manière persistante la réponse. Vous devez transférer le contexte de conversation vous-même en transmettant les éléments de sortie précédents comme entrée à la requête suivante.

Cette approche est utile lorsque vous avez besoin d’un contrôle total sur l’état de conversation, de réduire les données stockées ou de travailler dans un environnement de rétention de données zéro.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

Conversations et éléments de conversation

Les conversations sont des objets durables avec des identificateurs uniques. Après la création, vous pouvez les réutiliser entre les sessions.

Les conversations stockent des éléments, qui peuvent inclure des messages, des appels d’outils, des sorties d’outil et d’autres données.

Créer une conversation

L’exemple suivant crée une conversation avec un message utilisateur initial. Utilisez le client OpenAI (obtenu à partir du client de projet) pour les conversations et les réponses.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

Quand utiliser une conversation

Utilisez une conversation lorsque vous souhaitez :

  • Continuité multitour : conservez une histoire stable à travers les tours sans reconstruire vous-même le contexte.
  • Continuité intersession : réutiliser la même conversation pour un utilisateur qui retourne ultérieurement.
  • Débogage plus facile : inspectez ce qui s’est passé au fil du temps (par exemple, les appels d’outils et les sorties).

Lorsqu’une conversation est utilisée pour générer une réponse (avec ou sans agent), la conversation complète est fournie en tant qu’entrée au modèle. La réponse générée est ensuite ajoutée à la même conversation.

Note

Si la conversation dépasse la taille de contexte prise en charge du modèle, le modèle tronque automatiquement le contexte d’entrée. La conversation elle-même n’est pas tronquée, mais uniquement un sous-ensemble utilisé pour générer la réponse.

Si vous ne créez pas de conversation, vous pouvez toujours générer des flux à plusieurs tour en utilisant la sortie d’une réponse précédente comme point de départ pour la requête suivante. Cette approche vous offre plus de flexibilité que le modèle basé sur un thread plus ancien, où l’état a été étroitement couplé aux objets de thread. Pour obtenir des conseils sur la migration, consultez Migrer vers le Kit de développement logiciel (SDK) Agents.

Types d’éléments de conversation

Les conversations stockent des éléments plutôt que des messages de conversation uniquement. Les éléments capturent ce qui s’est passé pendant la génération de réponse afin que le tour suivant puisse réutiliser ce contexte.

Les types d’éléments courants sont les suivants :

  • Éléments de message : messages utilisateur ou assistant.
  • Éléments d'appel d'outil : enregistrements des appels d’outil tentés par l’agent.
  • Éléments de sortie de l’outil : sorties retournées par les outils (par exemple, résultats de récupération).
  • Éléments de sortie : contenu de réponse que vous affichez à l’utilisateur.

Ajouter des éléments à une conversation

Après avoir créé une conversation, utilisez cette option conversations.items.create() pour ajouter des messages utilisateur ou d’autres éléments suivants.

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

Utiliser une conversation avec un agent

Associez une conversation à une référence d’agent afin de conserver l’historique sur plusieurs échanges. L’agent traite tous les éléments de la conversation et ajoute automatiquement son résultat.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

Pour obtenir des exemples qui montrent comment les conversations et les réponses fonctionnent ensemble dans le code, consultez Créer et utiliser la mémoire dans le service De l’agent Foundry.

Diffusion en continu et réponses en arrière-plan

Pour les opérations de longue durée, vous pouvez retourner des résultats de manière incrémentielle à l’aide streaming ou exécuter complètement de manière asynchrone à l’aide du background mode. Dans ces cas, vous surveillez généralement la réponse jusqu’à ce qu’elle se termine, puis consommez les éléments de sortie finaux.

Diffuser en continu une réponse

Le streaming retourne des résultats partiels au fur et à mesure qu’ils sont générés. Cette approche est utile pour montrer la sortie aux utilisateurs en temps réel.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Pour plus d’informations sur les modes de réponse et sur la façon de consommer des sorties, consultez l’API Réponses.

Exécuter un agent en mode arrière-plan

Le mode d’arrière-plan exécute l’agent de manière asynchrone, ce qui est utile pour les tâches longues telles que le raisonnement complexe ou la génération d’images. Définissez background sur true, puis vérifiez l’état de la réponse jusqu’à ce que l’opération soit terminée.

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

Attacher de la mémoire à un agent (version préliminaire)

La mémoire permet aux agents de conserver des informations entre les sessions, afin qu’ils puissent personnaliser les réponses et rappeler les préférences utilisateur au fil du temps. Sans mémoire, chaque conversation commence à partir de zéro.

Le service Agent Foundry fournit une solution de mémoire gérée (aperçu) que vous configurez via des magasins de mémoire. Un magasin de mémoire définit les types d’informations que l’agent doit conserver. Attachez un magasin de mémoire à votre agent et l’agent utilise des mémoires stockées comme contexte supplémentaire pendant la génération de réponse.

L’exemple suivant crée un magasin de mémoire et l’attache à un agent.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

Pour plus d’informations conceptuelles, consultez Memory in Foundry Agent Service. Pour obtenir des instructions complètes sur l’implémentation, consultez Créer et utiliser la mémoire.

Gestion de la sécurité et des données

Étant donné que les conversations et les réponses peuvent conserver le contenu et les sorties d’outils fournis par l’utilisateur, traitez les données d’exécution comme les données d’application :

  • Évitez de stocker des secrets dans les invites ou l’historique des conversations. Utilisez plutôt des connexions et des magasins de secrets managés (par exemple, Configurez une connexion Key Vault).
  • Utilisez le privilège minimum pour l'accès à l'outil. Lorsqu’un outil accède à des systèmes externes, l’agent peut potentiellement lire ou envoyer des données via cet outil.
  • Soyez prudent avec les services non-Microsoft. Si votre agent appelle des outils soutenus par des services non-Microsoft, certaines données peuvent être transmises à ces services. Pour connaître les considérations connexes, consultez Découvrir les outils dans les outils Foundry.

Limites et contraintes

Les limites peuvent dépendre du modèle, de la région et des outils que vous attachez (par exemple, la disponibilité en streaming et la prise en charge des outils). Pour connaître la disponibilité et les contraintes actuelles des réponses, consultez l’API Réponses.

Contenu connexe

  • Last updated on