Agents en fonctionnement

L’abstraction de l’agent de base expose différentes options d’exécution de l’agent. Les appelants peuvent choisir de fournir zéro, un ou plusieurs messages d’entrée. Les appelants peuvent également choisir entre la diffusion en continu et la non-diffusion en continu. Examinons les différents scénarios d’utilisation.

Diffusion en continu et non streaming

Microsoft Agent Framework prend en charge les méthodes de diffusion en continu et de non-diffusion en continu pour l’exécution d’un agent.

Pour la non diffusion en continu, utilisez la RunAsync méthode.

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Pour la diffusion en continu, utilisez la RunStreamingAsync méthode.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.Write(update);
}

Pour la non diffusion en continu, utilisez la run méthode.

result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)

Pour la diffusion en continu, utilisez la run méthode avec stream=True. Cela retourne un ResponseStream objet qui peut être itéré de manière asynchrone :

async for update in agent.run("What is the weather like in Amsterdam?", stream=True):
    if update.text:
        print(update.text, end="", flush=True)

ResponseStream

L’objet ResponseStream retourné par run(..., stream=True) prend en charge deux modèles de consommation :

Modèle 1 : Itération asynchrone : traitez les mises à jour à mesure qu’elles arrivent pour l’affichage en temps réel :

response_stream = agent.run("Tell me a story", stream=True)
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

Modèle 2 : Finalisation directe : ignorer l’itération et obtenir la réponse complète :

response_stream = agent.run("Tell me a story", stream=True)
final = await response_stream.get_final_response()
print(final.text)

Modèle 3 : combiné : itérer pour l’affichage en temps réel, puis obtenir le résultat agrégé :

response_stream = agent.run("Tell me a story", stream=True)

# First, iterate to display streaming output
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

# Then get the complete response (uses already-collected updates, does not re-iterate)
final = await response_stream.get_final_response()
print(f"\n\nFull response: {final.text}")
print(f"Messages: {len(final.messages)}")

Options d’exécution de l’agent

L’abstraction de l’agent de base permet de transmettre un objet options pour chaque exécution de l’agent, mais la possibilité de personnaliser une exécution au niveau de l’abstraction est assez limitée. Les agents peuvent varier considérablement et, par conséquent, il n’existe pas vraiment d’options de personnalisation courantes.

Dans les cas où l’appelant connaît le type de l’agent avec lequel il travaille, il est possible de passer des options spécifiques de type pour permettre la personnalisation de l’exécution.

Par exemple, ici, l’agent est un ChatClientAgent et il est possible de passer un ChatClientAgentRunOptions objet qui hérite de AgentRunOptions. Cela permet à l’appelant de fournir des options personnalisées ChatOptions fusionnées avec toutes les options au niveau de l’agent avant d’être IChatClient passées à celle-ciChatClientAgent.

var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));

Les agents Python prennent en charge la personnalisation de chaque exécution via le options paramètre. Les options sont passées en tant que TypedDict et peuvent être définies à la fois au moment de la construction (via default_options) et par exécution (via options). Chaque fournisseur a sa propre classe TypedDict qui fournit la saisie semi-automatique de l’IDE complète et la vérification des types pour les paramètres spécifiques au fournisseur.

Les options courantes sont les suivantes :

max_tokens: nombre maximal de jetons à générer
temperature: contrôle l’aléatoire dans la génération de réponse
model_id: remplacer le modèle pour cette exécution spécifique
top_p: paramètre d’échantillonnage du noyau
response_format: spécifiez le format de réponse (par exemple, sortie structurée)

Note

Les tools paramètres restent instructions en tant qu’arguments de mot clé direct et ne sont pas transmis via le options dictionnaire.

from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

# Set default options at construction time
agent = OpenAIChatClient().as_agent(
    instructions="You are a helpful assistant",
    default_options={
        "temperature": 0.7,
        "max_tokens": 500
    }
)

# Run with custom options (overrides defaults)
# OpenAIChatOptions provides IDE autocomplete for all OpenAI-specific settings
options: OpenAIChatOptions = {
    "temperature": 0.3,
    "max_tokens": 150,
    "model_id": "gpt-4o",
    "presence_penalty": 0.5,
    "frequency_penalty": 0.3
}

result = await agent.run(
    "What is the weather like in Amsterdam?",
    options=options
)

# Streaming with custom options
async for update in agent.run(
    "Tell me a detailed weather forecast",
    stream=True,
    options={"temperature": 0.7, "top_p": 0.9},
    tools=[additional_weather_tool]  # tools is still a keyword argument
):
    if update.text:
        print(update.text, end="", flush=True)

Chaque fournisseur a sa propre classe TypedDict (par exemple, OpenAIChatOptions, , AnthropicChatOptionsOllamaChatOptions) qui expose l’ensemble complet d’options prises en charge par ce fournisseur.

Lorsque les options default_options par exécution et par exécution sont fournies, les options par exécution options sont prioritaires et sont fusionnées avec les valeurs par défaut.

Types de réponse

Les réponses de diffusion en continu et de non-diffusion en continu des agents contiennent tout le contenu produit par l’agent. Le contenu peut inclure des données qui ne sont pas le résultat (autrement dit, la réponse à la question de l’utilisateur) de l’agent. Parmi les autres données retournées, citons les appels d’outils de fonction, les résultats des appels d’outil de fonction, le texte de raisonnement, les mises à jour d’état, etc.

Étant donné que tout le contenu retourné n’est pas le résultat, il est important de rechercher des types de contenu spécifiques lors de la tentative d’isoler le résultat de l’autre contenu.

Pour extraire le résultat du texte d’une réponse, tous les TextContent éléments de tous les ChatMessages éléments doivent être agrégés. Pour simplifier ce problème, une Text propriété est disponible sur tous les types de réponse qui agrègent tous .TextContent

Pour le cas de non-diffusion en continu, tout est retourné dans un objet AgentResponse . AgentResponse autorise l’accès aux messages produits via la Messages propriété.

var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);

Pour le cas de diffusion en continu, AgentResponseUpdate les objets sont diffusés en continu à mesure qu’ils sont produits. Chaque mise à jour peut contenir une partie du résultat de l’agent, ainsi que d’autres éléments de contenu. Comme pour le cas de non diffusion en continu, il est possible d’utiliser la Text propriété pour obtenir la partie du résultat contenu dans la mise à jour et d’explorer les détails via la Contents propriété.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.WriteLine(update.Text);
    Console.WriteLine(update.Contents.Count);
}

Pour le cas de non-diffusion en continu, tout est retourné dans un objet AgentResponse . AgentResponse autorise l’accès aux messages produits via la messages propriété.

Pour extraire le résultat du texte d’une réponse, tous les TextContent éléments de tous les Message éléments doivent être agrégés. Pour simplifier ce problème, une Text propriété est disponible sur tous les types de réponse qui agrègent tous .TextContent

response = await agent.run("What is the weather like in Amsterdam?")
print(response.text)
print(len(response.messages))

# Access individual messages
for message in response.messages:
    print(f"Role: {message.role}, Text: {message.text}")

Pour le cas de diffusion en continu, AgentResponseUpdate les objets sont diffusés en continu à mesure qu’ils sont produits via le ResponseStream retour par run(..., stream=True). Chaque mise à jour peut contenir une partie du résultat de l’agent, ainsi que d’autres éléments de contenu. Comme pour le cas de non diffusion en continu, il est possible d’utiliser la text propriété pour obtenir la partie du résultat contenu dans la mise à jour et d’explorer les détails via la contents propriété.

response_stream = agent.run("What is the weather like in Amsterdam?", stream=True)
async for update in response_stream:
    print(f"Update text: {update.text}")
    print(f"Content count: {len(update.contents)}")

    # Access individual content items
    for content in update.contents:
        if hasattr(content, 'text'):
            print(f"Content: {content.text}")

# Get the aggregated final response after streaming
final = await response_stream.get_final_response()
print(f"Complete text: {final.text}")

Types de messages

Les entrées et sorties des agents sont représentées en tant que messages. Les messages sont subdivisés en éléments de contenu.

Microsoft Agent Framework utilise les types de message et de contenu fournis par les Microsoft.Extensions.AI abstractions. Les messages sont représentés par la ChatMessage classe et toutes les classes de contenu héritent de la classe de base AIContent .

Il existe différentes AIContent sous-classes utilisées pour représenter différents types de contenu. Certains sont fournis dans le cadre des abstractions de base Microsoft.Extensions.AI , mais les fournisseurs peuvent également ajouter leurs propres types, le cas échéant.

Voici quelques types populaires de Microsoft.Extensions.AI:

Type	Descriptif
TextContent	Contenu textuel qui peut être à la fois une entrée, par exemple, à partir d’un utilisateur ou d’un développeur et une sortie de l’agent. Contient généralement le résultat du texte d’un agent.
DataContent	Contenu binaire pouvant être à la fois d’entrée et de sortie. Peut être utilisé pour transmettre des données image, audio ou vidéo vers et depuis l’agent (où il est pris en charge).
UriContent	URL qui pointe généralement vers du contenu hébergé tel qu’une image, un audio ou une vidéo.
FunctionCallContent	Demande d’un service d’inférence pour appeler un outil de fonction.
FunctionResultContent	Résultat d’un appel d’outil de fonction.

Python Agent Framework utilise des types de messages et de contenu à partir du agent_framework package. Les messages sont représentés par la Message classe et toutes les classes de contenu héritent de la classe de base Content .

Différentes Content sous-classes existent qui sont utilisées pour représenter différents types de contenu :

Type	Descriptif
`Content`	Type de contenu unifié avec des méthodes de fabrique (`Content.from_text()`, `Content.from_data()`, `Content.from_uri()`). Utilisez la propriété pour vérifier le `type` type de contenu (« text », « data », « uri »).
`FunctionCallContent`	Demande d’un service IA pour appeler un outil de fonction.
`FunctionResultContent`	Résultat d’un appel d’outil de fonction.
`ErrorContent`	Informations d’erreur lors de l’échec du traitement.
`UsageContent`	Informations d’utilisation et de facturation des jetons du service IA.

Voici comment utiliser différents types de contenu :

from agent_framework import Message, Content

# Create a text message
text_message = Message(role="user", contents=["Hello!"])

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = Message(
    role="user",
    contents=[
        Content.from_text("Analyze this image:"),
        Content.from_data(data=image_data, media_type="image/png"),
    ]
)

# Access content from responses
response = await agent.run("Describe the image")
for message in response.messages:
    for content in message.contents:
        if content.type == "text":
            print(f"Text: {content.text}")
        elif content.type == "data":
            print(f"Data URI: {content.uri}")
        elif content.type == "uri":
            print(f"External URI: {content.uri}")

Prochaines étapes

Multimodal

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-02-13