Exploración del kernel semántico BedrockAgent

La documentación de la API de BedrockAgent estará disponible próximamente.

La documentación de la API de BedrockAgent estará disponible próximamente.

Característica actualmente no disponible en Java.

Agregue el paquete Semantic Kernel Bedrock Agents al proyecto de .NET:

dotnet add package Microsoft.SemanticKernel.Agents.Bedrock --prerelease

Esto incorporará la compatibilidad del SDK de kernel semántico para Bedrock, incluidas las dependencias del SDK de AWS para Bedrock. Es posible que también tenga que configurar las credenciales de AWS (por ejemplo, a través de variables de entorno o la configuración predeterminada de AWS). El SDK de AWS usará sus credenciales configuradas; asegúrese de que tiene establecida la región predeterminada en AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, y en su entorno o perfil de AWS. (Consulte la documentación de AWS sobre la configuración de credenciales para obtener más detalles).

Instale el paquete de kernel semántico con los extras de AWS:

pip install semantic-kernel[aws]

Esto garantiza que las bibliotecas de AWS necesarias (por ejemplo, boto3) se instalen junto con el kernel semántico. Antes de usar un agente de Bedrock en Python, asegúrese de que las credenciales y la región de AWS estén configuradas correctamente (por ejemplo, estableciendo variables de entorno o mediante la CLI de AWS). Debería tener AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY y AWS_DEFAULT_REGION (o perfil de AWS) establecidos para que boto3 pueda autenticarse.

Característica actualmente no disponible en Java.

using Amazon.Bedrock;
using Amazon.Bedrock.Model;
using Amazon.BedrockRuntime;
using Microsoft.SemanticKernel.Agents.Bedrock;

// 1. Define a new agent on the Amazon Bedrock service
IAmazonBedrock bedrockClient = new AmazonBedrockClient();  // uses default AWS credentials & region
var createRequest = new CreateAgentRequest 
{
    AgentName = "<foundation model ID>",          // e.g., "anthropic.claude-v2" or other model
    FoundationModel = "<foundation model ID>",    // the same model, or leave null if AgentName is the model
    AgentResourceArn = "<agent role ARN>",        // IAM role ARN with Bedrock permissions
    Instruction = "<agent instructions>"
};
CreateAgentResponse createResponse = await bedrockClient.CreateAgentAsync(createRequest);

// (Optional) Provide a description as needed:
// createRequest.Description = "<agent description>";

// After creation, the agent is in a "NOT_PREPARED" state.
// Prepare the agent to load tools and finalize setup:
await bedrockClient.PrepareAgentAsync(new PrepareAgentRequest 
{
    AgentId = createResponse.Agent.AgentId
});

// 2. Create a Semantic Kernel agent instance from the Bedrock agent definition
IAmazonBedrockRuntime runtimeClient = new AmazonBedrockRuntimeClient();
BedrockAgent agent = new BedrockAgent(createResponse.Agent, bedrockClient, runtimeClient);

En el código anterior, primero usamos aws SDK (AmazonBedrockClient) para crear un agente en Bedrock, especificando el modelo de base, un nombre, las instrucciones y el ARN del rol de IAM que el agente debe asumir. El servicio Bedrock responde con una definición de agente (incluido un AgentId único). A continuación, llamamos PrepareAgentAsync a para realizar la transición del agente a un estado listo (el agente pasará de un estado CREATING a NOT_PREPARED y, a continuación, a PREPARADO una vez listo). Por último, creamos un BedrockAgent objeto mediante la definición devuelta y los clientes de AWS. Esta BedrockAgent instancia es lo que usaremos para enviar mensajes y recibir respuestas.

import boto3
from semantic_kernel.agents import BedrockAgent

# 1. Define and prepare a new agent on Amazon Bedrock
agent = await BedrockAgent.create_and_prepare_agent(
    name="<agent name>", 
    instructions="<agent instructions>",
    foundation_model="<foundation model ID>",
    agent_resource_role_arn="<agent role ARN>"
)

En el ejemplo anterior, BedrockAgent.create_and_prepare_agent controla el flujo de creación completo: usa la configuración de AWS (a través de boto3) para crear un agente en Bedrock con el nombre, el modelo de base y las instrucciones especificados y, a continuación, espera automáticamente a que el agente alcance un estado listo (realizando el paso de preparación internamente). El resultado es una BedrockAgent instancia lista para usarse. En segundo plano, este método está creando clientes de AWS (para Bedrock y Bedrock Runtime) con sus credenciales predeterminadas, así que asegúrese de que su entorno de AWS esté configurado. Si necesita una configuración personalizada, también puede construir manualmente los clientes de AWS y pasarlos como parámetros (por ejemplo, client= boto3.client("bedrock") y runtime_client= boto3.client("bedrock-runtime")) a la create_and_prepare_agent llamada.

Característica actualmente no disponible en Java.

Para .NET, el identificador del agente de Bedrock es una cadena accesible a través de agent.Id. Para recuperar un agente existente por identificador, use el cliente de AWS Bedrock y, a continuación, construya un nuevo BedrockAgent:

string existingAgentId = "<your agent ID>";
var getResponse = await bedrockClient.GetAgentAsync(new GetAgentRequest { AgentId = existingAgentId });
BedrockAgent agent = new BedrockAgent(getResponse.Agent, bedrockClient, runtimeClient);

Aquí llamamos GetAgentAsync al IAmazonBedrock cliente con el identificador conocido, que devuelve la definición del agente (nombre, modelo, instrucciones, etc.). A continuación, inicializamos un nuevo BedrockAgent con esa definición y los mismos clientes. Esta instancia de agente se conectará al agente Bedrock ya existente.

En Python, puede recuperar de forma similar un agente mediante su ID con el cliente boto3 de AWS Bedrock, y luego encapsularlo en BedrockAgent.

import asyncio, boto3
from semantic_kernel.agents import BedrockAgent

agent_id = "<your agent ID>"
bedrock_client = boto3.client("bedrock")  # Bedrock service client
# Fetch the agent's definition from AWS
agent_info = await asyncio.to_thread(bedrock_client.get_agent, AgentId=agent_id)
# Create the BedrockAgent instance from the retrieved definition
agent = BedrockAgent(agent_model=agent_info["agent"])

En este fragmento, usamos boto3 para realizar la llamada get_agent al servicio Bedrock (ejecutándolo en un hilo mediante asyncio.to_thread, ya que boto3 es bloqueante). El agent_info["agent"] devuelto contiene los detalles del agente (id, nombre, estado, etc.), que pasamos al constructor de BedrockAgent. Dado que no proporcionamos explícitamente clientes de AWS a BedrockAgent, creará internamente nuevos clientes con la configuración predeterminada. (Opcionalmente, podría proporcionar client= y runtime_client= para reutilizar clientes si los tiene).

Característica actualmente no disponible en Java.

La clase BedrockAgentThread abstrae los detalles específicos del subproceso del agente de Bedrock (que implementa la interfaz común AgentThread). Actualmente, el BedrockAgent solo admite subprocesos de tipo BedrockAgentThread.

BedrockAgent agent = /* (your BedrockAgent instance, as created above) */;

// Start a new conversation thread for the agent
AgentThread agentThread = new BedrockAgentThread(runtimeClient);
try
{
    // Send a user message and iterate over the response(s)
    var userMessage = new ChatMessageContent(AuthorRole.User, "<your user input>");
    await foreach (ChatMessageContent response in agent.InvokeAsync(userMessage, agentThread))
    {
        Console.WriteLine(response.Content);
    }
}
finally
{
    // Clean up the thread and (optionally) the agent when done
    await agentThread.DeleteAsync();
    await agent.Client.DeleteAgentAsync(new DeleteAgentRequest { AgentId = agent.Id });
}

En este ejemplo, se crea explícitamente un BedrockAgentThread objeto (pasando en el runtimeClient, que usa para comunicarse con el servicio de tiempo de ejecución Bedrock). A continuación, llamamos a agent.InvokeAsync(...) con un ChatMessageContent que representa el mensaje de un usuario. InvokeAsync devuelve un flujo asincrónico de respuestas: en la práctica, un agente de Bedrock normalmente devuelve una respuesta final por invocación (ya que las acciones de herramienta intermedias se controlan por separado), por lo que normalmente obtendrá una única ChatMessageContent respuesta del bucle. Imprimimos la respuesta del asistente (response.Content). En el bloque finally, eliminamos el subproceso, que finaliza la sesión de Bedrock en AWS. También eliminamos el propio agente en este caso (ya que lo creamos solo para este ejemplo): este paso es opcional y solo es necesario si no tiene intención de volver a usar el agente (consulte Eliminar un BedrockAgent a continuación).

Puede continuar una conversación existente reutilizando lo mismo agentThread para las llamadas posteriores. Por ejemplo, puede leer en bucle la entrada del usuario y llamar a InvokeAsync cada vez con el mismo subproceso para llevar a cabo un diálogo de varios turnos. También puede crear un BedrockAgentThread con un identificador de sesión conocido para reanudar una conversación que se guardó anteriormente:

string sessionId = "<existing Bedrock session ID>";
AgentThread thread = new BedrockAgentThread(runtimeClient, sessionId);
// Now `InvokeAsync` using this thread will continue the conversation from that session

El uso de un agente de Bedrock en Python es similar, con el BedrockAgentThread gestionando la sesión. Puede iniciar un nuevo hilo o pasar uno existente para continuar una conversación.

from semantic_kernel.agents import BedrockAgentThread

# Assume `agent` is your BedrockAgent instance
USER_INPUTS = ["Hello", "What's your name?"]

thread = BedrockAgentThread()  # start a new conversation thread (session)
try:
    for user_input in USER_INPUTS:
        response = await agent.get_response(messages=user_input, thread=thread)
        print(response)  # print the assistant's reply
        thread = response.thread  # update thread (BedrockAgentThread) for next turn
finally:
    await thread.delete() if thread else None

En este código, recorremos algunas entradas de usuario. En cada iteración, llamamos agent.get_response(...) con el mensaje de usuario y el subproceso actual. La primera llamada inicia la sesión de Bedrock y devuelve un AgentResponseItem (o ChatMessageContent) que contiene la respuesta del asistente. Se imprime la respuesta y, a continuación, se toma el response.thread, el cual es el mismo BedrockAgentThread actualizado con el nuevo contexto de mensaje, para usarlo en el siguiente turno. Después de la conversación (en este ejemplo, dos turnos), eliminamos el hilo para finalizar la sesión en AWS.

Si omite el thread parámetro en la llamada, agent.get_response o agent.invoke creará automáticamente un nuevo subproceso para esa invocación e lo incluirá en la respuesta.

Opcionalmente, también puede enviar un lote de mensajes a la vez pasando una lista de mensajes a get_response o mediante la invocación de streaming asincrónica. Por ejemplo, para transmitir la respuesta del asistente (token por token) para un único mensaje:

# Streaming a single response from the Bedrock agent
async for partial in agent.invoke_stream(messages="Tell me a joke.", thread=thread):
    print(partial.content, end="")

El invoke_stream(...) método produce ChatMessageContent objetos a medida que se genera la respuesta. Al iterar sobre él, puede generar la respuesta del asistente de forma incremental (aquí se imprimen caracteres sin una nueva línea para formar la respuesta completa).

Característica actualmente no disponible en Java.

Usa el cliente Bedrock para eliminar por ID de agente. Por ejemplo:

await bedrockAgent.Client.DeleteAgentAsync(new() { AgentId = bedrockAgent.Id });

Después de esta llamada, el estado del agente cambiará y ya no se podrá usar. (Si intenta invocar un agente eliminado, se producirá un error).

Llamar al método de eliminación del/de la agente. Por ejemplo:

await agent.delete_agent()

Esto llamará al servicio Bedrock para eliminar el agente (y marcar internamente el BedrockAgent objeto como eliminado). Puede comprobar comprobando agent.id o una marca si se proporciona (por ejemplo, _is_deleted).

Característica actualmente no disponible en Java.

from semantic_kernel.contents import ChatMessageContent, FunctionCallContent, FunctionResultContent
from semantic_kernel.functions import kernel_function

# Define a sample plugin with two functions
class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> str:
        return "Soup: Clam Chowder; Salad: Cobb Salad; Drink: Chai Tea"

    @kernel_function(description="Provides the price of a menu item.")
    def get_item_price(self, menu_item: str) -> str:
        return "$9.99"

# Callback to handle intermediate messages
async def handle_intermediate_steps(message: ChatMessageContent) -> None:
    for item in (message.items or []):
        if isinstance(item, FunctionCallContent):
            print(f"Function Call:> {item.name} with arguments: {item.arguments}")
        elif isinstance(item, FunctionResultContent):
            print(f"Function Result:> {item.result} for function: {item.name}")
        else:
            print(f"[Intermediate] {item}")

# Create the BedrockAgent with the plugin (assuming agent is not yet created above)
agent = await BedrockAgent.create_and_prepare_agent(
    name="MenuAgent",
    instructions="You are a restaurant assistant.",
    foundation_model="<model ID>",
    agent_resource_role_arn="<role ARN>",
    plugins=[MenuPlugin()]  # include our custom plugin
)

# Start a conversation with intermediate callback
thread = BedrockAgentThread()
user_queries = [
    "Hello!",
    "What are the specials today?",
    "What is the special drink?",
    "How much is that?"
]
try:
    for query in user_queries:
        print(f"# User: {query}")
        async for response in agent.invoke(messages=query, thread=thread, on_intermediate_message=handle_intermediate_steps):
            print(f"# Assistant: {response}")
            thread = response.thread
finally:
    await thread.delete() if thread else None
    await agent.delete_agent()

En este código, siempre que el agente necesite llamar a una función desde MenuPlugin (por ejemplo, get_specials o get_item_price), el callback mostrará una línea para la llamada de función y otra para el resultado de la función. La respuesta final del asistente para cada consulta de usuario se imprime como normal. Al observar el contenido intermedio, puede realizar un seguimiento de cómo llegó el agente a su respuesta (qué herramienta se usó, lo que devolvió, etc.).

Por ejemplo, la salida podría ser similar a la siguiente:

# User: Hello!
# Assistant: Hello! How can I assist you today?
# User: What are the specials today?
Function Call:> MenuPlugin-get_specials with arguments: {}
Function Result:> Soup: Clam Chowder; Salad: Cobb Salad; Drink: Chai Tea for function: MenuPlugin-get_specials
# Assistant: The specials today include Clam Chowder for the soup, Cobb Salad, and Chai Tea as a special drink.
# User: What is the special drink?
# Assistant: The special drink is Chai Tea.
# User: How much is that?
Function Call:> MenuPlugin-get_item_price with arguments: {"menu_item": "Chai Tea"}
Function Result:> $9.99 for function: MenuPlugin-get_item_price
# Assistant: The special drink (Chai Tea) costs $9.99.

En la interacción anterior, las impresiones intermedias muestran que el agente llamó MenuPlugin.get_specials correctamente y MenuPlugin.get_item_price en los momentos adecuados, y usó sus resultados para responder al usuario. Estos detalles intermedios se pueden registrar o usar en la lógica de la aplicación según sea necesario (por ejemplo, para mostrar los pasos que tomó el agente).

El soporte de devolución de llamada para mensajes intermedios en BedrockAgent (C#) sigue un patrón similar, pero la API exacta está en desarrollo. (Las versiones futuras permitirán registrar un delegado para controlar FunctionCallContent y FunctionResultContent durante InvokeAsync.

Característica actualmente no disponible en Java.

El uso de una especificación declarativa puede simplificar la configuración, especialmente si desea cambiar fácilmente las configuraciones del agente o usar un enfoque de archivo de configuración. En el caso de un agente de Bedrock, una definición de YAML podría ser similar a la siguiente:

type: bedrock_agent
name: MenuAgent
description: Agent that answers questions about a restaurant menu
instructions: You are a restaurant assistant that provides daily specials and prices.
model:
  id: anthropic.claude-v2
agent_resource_role_arn: arn:aws:iam::123456789012:role/BedrockAgentRole
tools:
  - type: code_interpreter
  - type: user_input
  - name: MenuPlugin
    type: kernel_function

En este YAML (hipotético), definimos un agente de tipo bedrock_agent, le asignamos un nombre e instrucciones, especificamos el modelo de base por identificador y proporcionamos el ARN del rol que debe usar. También declaramos un par de herramientas: una habilitación del intérprete de código integrado, otra habilitación de la herramienta de entrada de usuario integrada y un MenuPlugin personalizado (que se definiría por separado en el código y registrado como una función de kernel). Este archivo encapsula la configuración del agente en un formulario legible.

Para crear una instancia de un agente de YAML, use el cargador estático con un generador adecuado. Por ejemplo:

string yamlText = File.ReadAllText("bedrock-agent.yaml");
var factory = new BedrockAgentFactory();  // or an AggregatorAgentFactory if multiple types are used
Agent myAgent = await KernelAgentYaml.FromAgentYamlAsync(kernel, yamlText, factory);

Esto analizará YAML y generará una BedrockAgent instancia (u otro tipo basado en el type campo) mediante el kernel y el generador proporcionados.

La gestión de las Especificaciones declarativas de BedrockAgent estará disponible próximamente.

Característica actualmente no disponible en Java.