Construire avec des agents, des interactions et des réactions

Microsoft Foundry Agent Service utilise trois composants d’exécution principaux : agents, conversations et réponses pour alimenter les interactions à plusieurs tours avec conservation d'état. Un agent utilise un modèle à partir du catalogue de modèles Foundry, ainsi que des instructions et des outils. Une conversation maintient l’historique à travers les échanges. 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 dans Python, C#, JavaScript, Java 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, transmettez le contexte en utilisant le résultat d'une réponse précédente.
  • Générez une réponse : le modèle Foundry de l’agent traite les éléments d’entrée dans la conversation et toutes les instructions fournies dans la requête. 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 boucle d’agent classique.

Diagramme montrant la boucle d’exécution de l’agent : une définition d’agent et une génération de réponse de flux d’historique de conversation facultative, qui peut appeler des outils, ajouter 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.

Conditions préalables

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.

Step 2: L’exemple suivant crée un agent de dialogue 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 plus de types d’agents supplémentaires (workflow, hébergé), consultez le cycle de vie du développement de l’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éponse 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.

En outre, vous pouvez bifurquer la conversation au premier identifiant de réponse ou au deuxième identifiant de 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 pouvez donc référencer le contexte multitour previous_response_id. Si vous définissez store sur false, le service ne conserve pas 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 un historique stable au fil des 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’un outil : enregistrements des appels d’outil réalisé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 pour conserver l’historique à travers plusieurs échanges. L’agent traite tous les éléments de la conversation et ajoute automatiquement le 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 à true et interrogez ensuite le statut de la réponse jusqu'à ce que ce soit terminé.

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)

Associer de la mémoire à un agent (aperçu)

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 Foundry Agent fournit une solution de gestion de mémoire gérée (version préliminaire) 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 aux outils. Lorsqu’un outil accède à des systèmes externes, l’agent peut potentiellement lire ou envoyer des données via cet outil.
  • Faites attention aux services non-Microsoft. Si votre agent appelle des outils soutenus par des non-services Microsoft, certaines données peuvent être transmises à ces services. Pour connaître les considérations connexes, consultez Explorer les outils dans les outils de fonderie.

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