Compartir a través de

Interfaz del API del agente común del Kernel Semántico

Los agentes de kernel semántico implementan una interfaz unificada para la invocación, lo que permite el código compartido que funciona sin problemas entre diferentes tipos de agente. Este diseño permite cambiar los agentes según sea necesario sin modificar la mayoría de la lógica de la aplicación.

Invocación de un agente

La interfaz de la API del agente soporta tanto la invocación en streaming como la sin streaming.

Invocación de agente no transmitida

El Kernel Semántico admite cuatro sobrecargas de invocación de agente, que no son de transmisión, lo que permite pasar mensajes de diferentes maneras. Uno de estos también permite invocar al agente sin mensajes. Esto es útil para escenarios en los que las instrucciones del agente ya tienen todo el contexto necesario para proporcionar una respuesta útil.

// 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?")
});

Importante

Invocar un agente sin pasar un AgentThread al InvokeAsync método creará un nuevo subproceso y devolverá el nuevo subproceso en la respuesta.

El kernel semántico admite dos métodos de invocación de agente que no son de streaming que permiten pasar mensajes de diferentes maneras. También es posible invocar al agente sin mensajes. Esto es útil para escenarios en los que las instrucciones del agente ya tienen todo el contexto necesario para proporcionar una respuesta útil.

Sugerencia

Todos los argumentos pasados a los métodos de invocación del agente requieren que el autor de la llamada los pase como argumentos de palabra clave, excepto para el primer argumento posicional, messages. Puede invocar con un argumento posicional o una palabra clave para messages. Tanto await agent.get_response("What is the capital of France?") como await agent.get_response(messages="What is the capital of France?") se admiten. Todos los demás parámetros se deben pasar como argumentos de palabra clave.

Uso del método 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?"),
    ]
)

Uso del método 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

Importante

La invocación de un agente sin pasar un AgentThread a los métodos get_response() o invoke() creará un nuevo subproceso y devolverá el nuevo subproceso en la respuesta.

El kernel semántico admite tres sobrecargas de invocaciones de agente no streaming que permiten pasar mensajes de diferentes maneras. Uno de estos también permite invocar al agente sin mensajes. Esto es útil para escenarios en los que las instrucciones del agente ya tienen todo el contexto necesario para proporcionar una respuesta útil.

// 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?")
));

Importante

Invocar un agente sin pasar un AgentThread al invokeAsync método creará un nuevo subproceso y devolverá el nuevo subproceso en la respuesta.

Invocación del agente de streaming

El kernel semántico admite cuatro sobrecargas de invocación del agente de streaming que permiten pasar mensajes de diferentes maneras. Uno de estos también permite invocar al agente sin mensajes. Esto es útil para escenarios en los que las instrucciones del agente ya tienen todo el contexto necesario para proporcionar una respuesta útil.

// 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?")
});

Importante

Invocar un agente sin pasar un AgentThread al InvokeStreamingAsync método creará un nuevo subproceso y devolverá el nuevo subproceso en la respuesta.

El kernel semántico admite un método de invocación del agente de streaming que permite pasar mensajes de diferentes maneras. También es posible invocar la secuencia del agente sin mensajes. Esto es útil para escenarios en los que las instrucciones del agente ya tienen todo el contexto necesario para proporcionar una respuesta útil.

# 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

Importante

Invocar un agente sin pasar un AgentThread al invoke_stream() método creará un nuevo subproceso y devolverá el nuevo subproceso en la respuesta.

Característica actualmente no disponible en Java.

Invocando con un AgentThread

Todas las sobrecargas del método de invocación permiten pasar un parámetro AgentThread. Esto es útil para escenarios en los que tiene una conversación existente con el agente que desea continuar.

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

Todos los métodos de invocación también devuelven el elemento activo AgentThread como parte de la respuesta de invocación.

  1. Si ha pasado un AgentThread al método invoke, el devuelto AgentThread será el mismo que el que se pasó.
  2. Si no pasaste ningún AgentThread al método invoke, el AgentThread devuelto será un nuevo AgentThread.

El devuelto AgentThread está disponible en los elementos de respuesta individuales de los métodos de invocación junto con el mensaje de respuesta.

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

Sugerencia

Para obtener más información sobre los subprocesos del agente, consulte la sección Arquitectura de subprocesos del agente.

Todos los argumentos de palabra clave del método de invocación permiten pasar un AgentThread parámetro. Esto es útil para escenarios en los que tiene una conversación existente con el agente que desea continuar.

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

Todos los métodos de invocación también devuelven el elemento activo AgentThread como parte de la respuesta de invocación.

  1. Si ha pasado un AgentThread al método invoke, el devuelto AgentThread será el mismo que el que se pasó.
  2. Si no pasaste ningún AgentThread al método invoke, el AgentThread devuelto será un nuevo AgentThread.

El devuelto AgentThread está disponible en los elementos de respuesta individuales de los métodos de invocación junto con el mensaje de respuesta.

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

Sugerencia

Para obtener más información sobre los subprocesos del agente, consulte la sección Arquitectura de subprocesos del agente.

Dos sobrecargas del método de invocación permiten pasar un parámetro AgentThread. Esto es útil para escenarios en los que tiene una conversación existente con el agente que desea continuar.

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

Estos métodos de invocación también devuelven el elemento activo AgentThread como parte de la respuesta de invocación.

  1. Si ha pasado un AgentThread al método invoke, el devuelto AgentThread será una nueva instancia con los mensajes anteriores y nuevos.
  2. Si no pasaste ningún AgentThread al método invoke, el AgentThread devuelto será un nuevo AgentThread.

El devuelto AgentThread está disponible en los elementos de respuesta individuales de los métodos de invocación junto con el mensaje de respuesta.

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

Sugerencia

Para obtener más información sobre los subprocesos del agente, consulte la sección Arquitectura de subprocesos del agente.

Invocación con opciones

Todas las sobrecargas del método de invocación permiten pasar un parámetro AgentInvokeOptions. Esta clase de opciones permite proporcionar cualquier configuración opcional.

// 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."
});

Esta es la lista de las opciones admitidas.

Opción (propiedad) Descripción
Núcleo (Kernel) Invalide el kernel predeterminado usado por el agente para esta invocación.
Argumentos del Núcleo Invalide los argumentos de kernel predeterminados usados por el agente para esta invocación.
Instrucciones Adicionales Proporcione instrucciones adicionales al conjunto de instrucciones del agente original, que solo se apliquen a esta invocación.
OnIntermediateMessage Un callback que puede recibir todos los mensajes totalmente formados generados dentro del Agente, incluidos los mensajes de llamada de función e invocación de función. También se puede usar para recibir mensajes completos durante una invocación de streaming.

Invocación con opciones

Una sobrecarga de método de invocación permite pasar un AgentInvokeOptions parámetro. Esta clase de opciones permite proporcionar cualquier configuración opcional.

// 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()
);

Esta es la lista de las opciones admitidas.

Opción (propiedad) Descripción
Núcleo (Kernel) Invalide el kernel predeterminado usado por el agente para esta invocación.
Argumentos del Núcleo Invalide los argumentos de kernel predeterminados usados por el agente para esta invocación.
Instrucciones Adicionales Proporcione instrucciones adicionales al conjunto de instrucciones del agente original, que solo se apliquen a esta invocación.
Contexto de Invocación Invalide el contexto de invocación predeterminado que usa el agente para esta invocación.

Administración de instancias de AgentThread

Puede crear manualmente una AgentThread instancia y pasarla al agente en la invocación, o puede permitir que el agente cree automáticamente una AgentThread instancia en la invocación. Un AgentThread objeto representa un hilo en todos sus estados, incluidos: aún no creado, activo y eliminado.

AgentThread Los tipos que tienen una implementación del lado servidor se crearán en el primer uso y no es necesario crear manualmente. Sin embargo, puede eliminar un hilo usando la clase AgentThread.

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

# Delete a thread
await agent_thread.delete()

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

Sugerencia

Para obtener más información sobre los subprocesos del agente, consulte la sección Arquitectura de subprocesos del agente.

Pasos siguientes

Configuración de agentes con complementos

Explora el agente de finalización de chat