Partager via

Surface de l’API Agent Commun du Noyau Sémantique

Les agents de noyau sémantique implémentent une interface unifiée pour l’appel, activant le code partagé qui fonctionne en toute transparence entre différents types d’agents. Cette conception vous permet de changer les agents si nécessaire sans modifier la majorité de votre logique d’application.

Appel d’un agent

La surface de l'API Agent prend en charge les invocations en flux et non en flux.

Appel de l’agent hors streaming

Le noyau sémantique prend en charge quatre surcharges d'appel d'agent non-streaming permettant de transmettre des messages de différentes manières. L’un d’eux permet également d’appeler l’agent sans messages. Cela est utile pour les scénarios où les instructions de l’agent ont déjà tout le contexte requis pour fournir une réponse utile.

// Invoke without any parameters.
agent.InvokeAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer all user questions about France."),
    new(AuthorRole.User, "What is the capital of France?")
});

Important

Exécuter un agent sans passer une AgentThread à la méthode InvokeAsync créera un nouveau thread et retournera le nouveau thread dans la réponse.

Le noyau sémantique prend en charge deux méthodes d'appel d'agent non diffusées en continu qui permettent de passer des messages de différentes manières. Il est également possible d’appeler l’agent sans messages. Cela est utile pour les scénarios où les instructions de l’agent ont déjà tout le contexte requis pour fournir une réponse utile.

Conseil / Astuce

Tous les arguments passés aux méthodes d’appel de l’agent nécessitent que l’appelant les passe en tant qu’arguments de mot clé, à l’exception du premier argument positionnel, messages. Vous pouvez appeler avec un argument positionnel ou un argument de mot clé pour messages. Par exemple, à la fois await agent.get_response("What is the capital of France?") et await agent.get_response(messages="What is the capital of France?") sont pris en charge. Tous les autres paramètres doivent être passés en tant qu’arguments de mot clé.

Utilisation de la méthode get_response()

# Invoke without any messages.
await agent.get_response()

# Invoke with a string that will be used as a User message.
await agent.get_response(messages="What is the capital of France?")

# Invoke with a ChatMessageContent object.
await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))

# Invoke with multiple ChatMessageContent objects.
await agent.get_response(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
)

Utilisation de la méthode invoke()

# Invoke without any messages.
async for response in agent.invoke():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Important

L'invocation d'un agent sans passer un AgentThread à la méthode get_response() ou invoke() créera un nouveau thread et retournera le nouveau thread dans la réponse.

Le noyau sémantique prend en charge trois surcharges d'invocation d'agent non streaming qui permettent de transmettre des messages de différentes manières. L’un d’eux permet également d’appeler l’agent sans messages. Cela est utile pour les scénarios où les instructions de l’agent ont déjà tout le contexte requis pour fournir une réponse utile.

// Invoke without any parameters.
agent.invokeAsync(null);

// Invoke with a string that will be used as a User message.
agent.invokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.invokeAsync(List.of(
    new ChatMessageContent<>(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
    new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?")
));

Important

Exécuter un agent sans passer une AgentThread à la méthode invokeAsync créera un nouveau thread et retournera le nouveau thread dans la réponse.

Appel de l’agent de streaming

Le noyau sémantique prend en charge quatre surcharges d’appel d’agent de streaming qui permettent de transmettre des messages de différentes façons. L’un d’eux permet également d’appeler l’agent sans messages. Cela est utile pour les scénarios où les instructions de l’agent ont déjà tout le contexte requis pour fournir une réponse utile.

// Invoke without any parameters.
agent.InvokeStreamingAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeStreamingAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeStreamingAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeStreamingAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer any questions about capital cities."),
    new(AuthorRole.User, "What is the capital of France?")
});

Important

Exécuter un agent sans passer une AgentThread à la méthode InvokeStreamingAsync créera un nouveau thread et retournera le nouveau thread dans la réponse.

Le noyau sémantique prend en charge une méthode d’appel d’agent de diffusion en continu qui permet de transmettre des messages de différentes façons. Il est également possible d’invoquer le flux d’agent sans messages. Cela est utile pour les scénarios où les instructions de l’agent ont déjà tout le contexte requis pour fournir une réponse utile.

# Invoke without any messages.
async for response in agent.invoke_stream():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke_stream("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke_stream(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Important

Exécuter un agent sans passer une AgentThread à la méthode invoke_stream() créera un nouveau thread et retournera le nouveau thread dans la réponse.

Fonctionnalité actuellement indisponible en Java.

Invocation avec un AgentThread

Toutes les surcharges de méthode d'invocation autorisent le passage d'un paramètre AgentThread. Cela est utile pour les scénarios où vous avez une conversation existante avec l’agent que vous souhaitez continuer.

// Invoke with an existing AgentThread.
agent.InvokeAsync("What is the capital of France?", existingAgentThread);

Toutes les méthodes d’appel renvoient également l’actif AgentThread comme partie de la réponse d’appel.

  1. Si vous avez passé un AgentThread à la méthode invoke, le AgentThread retourné sera identique à celui qui a été passé en paramètre.
  2. Si vous n’avez passé aucun AgentThread à la méthode invoke, le retour AgentThread sera un nouveau AgentThread.

L'élément retourné AgentThread est disponible sur les éléments de réponse individuels des méthodes d'invocation, ainsi que le message de réponse.

var result = await agent.InvokeAsync("What is the capital of France?").FirstAsync();
var newThread = result.Thread;
var resultMessage = result.Message;

Conseil / Astuce

Pour plus d’informations sur les threads d’agent, consultez la section Architecture du thread d’agent.

Tous les arguments de mots-clés des méthodes d'invocation permettent de passer un paramètre AgentThread. Cela est utile pour les scénarios où vous avez une conversation existante avec l’agent que vous souhaitez continuer.

# Invoke with an existing AgentThread.
agent.get_response("What is the capital of France?", thread=existing_agent_thread)

Toutes les méthodes d’appel renvoient également l’actif AgentThread comme partie de la réponse d’appel.

  1. Si vous avez passé un AgentThread à la méthode invoke, le AgentThread retourné sera identique à celui qui a été passé en paramètre.
  2. Si vous n’avez passé aucun AgentThread à la méthode invoke, le retour AgentThread sera un nouveau AgentThread.

L'élément retourné AgentThread est disponible sur les éléments de réponse individuels des méthodes d'invocation, ainsi que le message de réponse.

response = await agent.get_response("What is the capital of France?")
new_thread = response.thread
response_message = response.message

Conseil / Astuce

Pour plus d’informations sur les threads d’agent, consultez la section Architecture du thread d’agent.

Deux surcharges de méthode d’appel permettent de transmettre un AgentThread paramètre. Cela est utile pour les scénarios où vous avez une conversation existante avec l’agent que vous souhaitez continuer.

// Invoke with an existing AgentThread.
agent.invokeAsync("What is the capital of France?", existingAgentThread);

Ces méthodes d’appel retournent également l’actif AgentThread comme partie de la réponse d’appel.

  1. Si vous avez passé un AgentThread à la méthode d'appel, la valeur de retour AgentThread sera une nouvelle instance avec les messages précédents et les nouveaux.
  2. Si vous n’avez passé aucun AgentThread à la méthode invoke, le retour AgentThread sera un nouveau AgentThread.

L'élément retourné AgentThread est disponible sur les éléments de réponse individuels des méthodes d'invocation, ainsi que le message de réponse.

var result = agent.invokeAsync("What is the capital of France?").block().get(0);
var newThread = result.getThread();
var resultMessage = result.getMessage();

Conseil / Astuce

Pour plus d’informations sur les threads d’agent, consultez la section Architecture du thread d’agent.

Invocation avec options

Toutes les surcharges de méthode d'invocation autorisent le passage d'un paramètre AgentInvokeOptions. Cette classe d’options permet de fournir tous les paramètres facultatifs.

// Invoke with additional instructions via options.
agent.InvokeAsync("What is the capital of France?", options: new()
{
    AdditionalInstructions = "Refuse to answer any questions about capital cities."
});

Voici la liste des options prises en charge.

Propriété d'option Descriptif
Noyau Remplacez le noyau par défaut utilisé par l’agent pour cette invocation.
KernelArguments Remplacez les arguments de noyau par défaut utilisés par l’agent pour cet appel.
Instructions supplémentaires Fournissez toutes les instructions en plus du jeu d’instructions de l’agent d’origine, qui s’appliquent uniquement à cet appel.
OnIntermediateMessage Fonction de rappel qui peut recevoir tous les messages entièrement formés générés en interne par l’Agent, y compris les messages d'appel et d'invocation de fonction. Cela peut également être utilisé pour recevoir des messages complets lors d'une invocation de flux en continu.

Invocation avec options

Une des surcharges de méthode d'invocation permet de passer un paramètre AgentInvokeOptions. Cette classe d’options permet de fournir tous les paramètres facultatifs.

// Invoke with additional instructions via options.
agent.invokeAsync("What is the capital of France?",
    null, // null AgentThread
    AgentInvokeOptions.builder()
        .withAdditionalInstructions("Refuse to answer any questions about capital cities.")
        .build()
);

Voici la liste des options prises en charge.

Propriété d'option Descriptif
Noyau Remplacez le noyau par défaut utilisé par l’agent pour cette invocation.
KernelArguments Remplacez les arguments de noyau par défaut utilisés par l’agent pour cet appel.
Instructions supplémentaires Fournissez toutes les instructions en plus du jeu d’instructions de l’agent d’origine, qui s’appliquent uniquement à cet appel.
Contexte d'Appel Remplacez le contexte d’appel par défaut que l’agent utilise pour cet appel.

Gestion des instances AgentThread

Vous pouvez créer manuellement une AgentThread instance et la transmettre à l’agent lors de l’appel, ou vous pouvez laisser l’agent créer une AgentThread instance pour vous automatiquement lors de l’appel. Un AgentThread objet représente un thread dans tous ses états, y compris : pas encore créé, actif et supprimé.

AgentThread Les types qui ont une implémentation côté serveur sont créés lors de la première utilisation et n’ont pas besoin d’être créés manuellement. Vous pouvez toutefois supprimer un thread à l’aide de la AgentThread classe.

// Delete a thread.
await agentThread.DeleteAsync();

# Delete a thread
await agent_thread.delete()

// Delete a thread.
agentThread.deleteAsync().block();

Conseil / Astuce

Pour plus d’informations sur les threads d’agent, consultez la section Architecture du thread d’agent.

Étapes suivantes

Configurer des agents avec des plug-ins

Explorer l'agent d'achèvement de chat

  • Last updated on