Explorando o kernel semântico BedrockAgent

Documentação da API BedrockAgent em breve.

Documentação da API BedrockAgent em breve.

Recurso atualmente indisponível em Java.

Adicione o pacote Semântico Kernel Bedrock Agents ao seu projeto .NET:

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

Isso trará suporte ao SDK do Kernel Semântico para o Bedrock, incluindo dependências do SDK da AWS para o Bedrock. Talvez você também precise configurar as credenciais do AWS (por exemplo, por meio de variáveis de ambiente ou da configuração padrão do AWS). O SDK do AWS usará suas credenciais configuradas; verifique se você tem seu AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e a região padrão configurados no seu ambiente ou perfil do AWS. (Consulte a documentação da AWS sobre a configuração de credenciais para obter mais detalhes.)

Instale o pacote kernel semântico com os extras do AWS:

pip install semantic-kernel[aws]

Isso garante que as bibliotecas AWS necessárias (por exemplo, boto3) sejam instaladas junto com Kernel Semântico. Antes de usar um Agente Bedrock no Python, verifique se suas credenciais e região do AWS estão configuradas corretamente (por exemplo, definindo variáveis de ambiente ou usando a CLI do AWS). Você deve ter AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYe AWS_DEFAULT_REGION (ou perfil AWS) definido para que o boto3 possa se autenticar.

Recurso atualmente indisponível em 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);

No código acima, primeiro usamos o SDK do AWS (AmazonBedrockClient) para criar um agente no Bedrock, especificando o modelo de base, um nome, as instruções e o ARN da função IAM que o agente deve assumir. O serviço Bedrock responde com uma definição de agente (incluindo uma AgentId exclusiva). Em seguida, chamamos PrepareAgentAsync para fazer a transição do agente para um estado pronto (o agente passará de um status CREATING para NOT_PREPARED e, em seguida, para PREPARED uma vez pronto). Por fim, criamos um BedrockAgent objeto usando a definição retornada e os clientes do AWS. Essa BedrockAgent instância é o que usaremos para enviar mensagens e receber respostas.

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>"
)

No exemplo acima, BedrockAgent.create_and_prepare_agent lida com o fluxo de criação completo: ele usa a configuração do AWS (via boto3) para criar um agente no Bedrock com o nome, o modelo de base e as instruções fornecidos e, em seguida, espera automaticamente que o agente atinja um estado pronto (executando a etapa de preparação internamente). O resultado é uma BedrockAgent instância pronta para uso. Sob o capô, esse método está criando clientes AWS (para Bedrock e Bedrock Runtime) usando suas credenciais padrão, portanto, verifique se o ambiente do AWS está configurado. Se você precisar de configuração personalizada, também poderá construir manualmente os clientes do AWS e passá-los como parâmetros (por exemplo, client= boto3.client("bedrock") e runtime_client= boto3.client("bedrock-runtime")) para a create_and_prepare_agent chamada.

Recurso atualmente indisponível em Java.

Para .NET, o identificador do agente Bedrock é uma cadeia de caracteres acessível por meio de agent.Id. Para recuperar um agente existente por ID, use o cliente AWS Bedrock e, em seguida, construa um novo BedrockAgent:

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

Aqui, chamamos GetAgentAsync o IAmazonBedrock cliente com a ID conhecida, que retorna a definição do agente (nome, modelo, instruções etc.). Em seguida, inicializamos um novo BedrockAgent com essa definição e os mesmos clientes. Essa instância do agente será vinculada ao agente Bedrock existente.

No Python, você também pode recuperar um agente por ID usando o cliente AWS Bedrock boto3 e embrulhá-lo em um 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"])

Neste trecho, usamos boto3 para chamar get_agent no serviço Bedrock (executando-o em um thread via asyncio.to_thread já que o boto3 é bloqueante). O elemento retornado agent_info["agent"] contém os detalhes do agente (como id, nome, status, etc.), que passamos para o construtor BedrockAgent. Como não fornecemos explicitamente clientes AWS, BedrockAgentele criará internamente novos clientes com configurações padrão. (Opcionalmente, você pode fornecer client= e runtime_client= para reutilizar clientes, se os tiver.)

Recurso atualmente indisponível em Java.

As especificidades do thread do agente Bedrock são abstraidas pela BedrockAgentThread classe (que implementa a interface comum AgentThread ). O BedrockAgent atualmente só dá suporte a threads do 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 });
}

Neste exemplo, criamos explicitamente um BedrockAgentThread (passando o runtimeClient, que ele utiliza para se comunicar com o serviço Bedrock Runtime). Em seguida, chamamos agent.InvokeAsync(...) com uma ChatMessageContent representando uma mensagem de um usuário. InvokeAsync retorna um fluxo assíncrono de respostas – na prática, um Agente Bedrock normalmente retorna uma resposta final por invocação (uma vez que as ações de ferramenta intermediária são tratadas separadamente), portanto, você geralmente obterá um único ChatMessageContent do loop. Imprimimos a resposta do assistente (response.Content). No bloco "finally", apagamos o thread, o que encerra a sessão Bedrock na AWS. Também excluimos o próprio agente nesse caso (já que o criamos apenas para este exemplo) – essa etapa é opcional e só é necessária se você não pretende reutilizar o agente novamente (consulte Excluir um BedrockAgent abaixo).

Você pode continuar uma conversa existente reutilizando o mesmo agentThread para chamadas subsequentes. Por exemplo, você pode fazer um loop lendo a entrada do usuário e chamando InvokeAsync cada vez com o mesmo thread para continuar um diálogo de várias voltas. Você também pode criar um BedrockAgentThread com uma ID de sessão conhecida para retomar uma conversa que foi salva 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

O uso de um Agente Bedrock no Python é semelhante, com o BedrockAgentThread gerenciando a sessão. Você pode iniciar um novo thread ou passar um existente para continuar uma conversa:

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

Nesse código, percorremos algumas poucas entradas de usuário. Em cada iteração, chamamos agent.get_response(...) com a mensagem do usuário e o thread atual. A primeira chamada inicia a sessão Bedrock e retorna um AgentResponseItem (ou ChatMessageContent) que contém a resposta do assistente. Imprimimos a resposta e, em seguida, pegamos o response.thread – que é o mesmo BedrockAgentThread atualizado com o novo contexto de mensagem – para usar na próxima vez. Após a conversa (neste exemplo, duas voltas), excluiremos o thread para encerrar a sessão no AWS.

Se você omitir o thread parâmetro na chamada agent.get_response ou agent.invoke criará automaticamente um novo thread para essa invocação e o incluirá na resposta.

Opcionalmente, você também pode enviar um lote de mensagens de uma só vez passando uma lista de mensagens para get_response ou usando a invocação de streaming assíncrona. Por exemplo, para transmitir a resposta do assistente (token por token) para uma única solicitação:

# 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="")

O invoke_stream(...) método produz ChatMessageContent objetos à medida que a resposta é gerada. Ao iterar sobre ele, você pode gerar a resposta do assistente de forma incremental (aqui imprimimos caracteres sem uma nova linha para formar a resposta completa).

Recurso atualmente indisponível em Java.

Use o cliente Bedrock para excluir por ID do agente. Por exemplo:

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

Após essa chamada, o status do agente será alterado e ele não será mais utilizável. (A tentativa de invocar um agente excluído resultará em um erro.)

Chame o método de exclusão do agente. Por exemplo:

await agent.delete_agent()

Isso chamará o serviço Bedrock para excluir o agente (e marcar internamente o BedrockAgent objeto como excluído). Você pode verificar consultando agent.id ou uma bandeira, se for fornecida (por exemplo, _is_deleted).

Recurso atualmente indisponível em 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()

Nesse código, sempre que o agente precisar chamar uma função de MenuPlugin (por exemplo, get_specials ou get_item_price), o handle_intermediate_steps retorno de chamada imprimirá uma linha para a chamada de função e outra para o resultado da função. A resposta final do assistente para cada consulta de usuário é impressa normalmente. Observando o conteúdo intermediário, você pode rastrear como o agente chegou à sua resposta (qual ferramenta foi usada, o que ele retornou etc.).

Por exemplo, a saída pode ser semelhante a:

# 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.

Na interação acima, as impressões intermediárias mostram que o agente chamou MenuPlugin.get_specials com êxito e MenuPlugin.get_item_price nos horários apropriados e usou seus resultados para responder ao usuário. Esses detalhes intermediários podem ser registrados ou usados na lógica do aplicativo conforme necessário (por exemplo, para exibir as etapas que o agente tomou).

O suporte de retorno de chamada para mensagens intermediárias no BedrockAgent (C#) segue um padrão semelhante, mas a API exata está em desenvolvimento. (Versões futuras permitirão o registro de um delegado para manipular FunctionCallContent e FunctionResultContent durante InvokeAsync.)

Recurso atualmente indisponível em Java.

O uso de uma especificação declarativa pode simplificar a configuração, especialmente se você quiser alternar facilmente as configurações do agente ou usar uma abordagem de arquivo de configuração. Para um Agente Bedrock, uma definição yaml pode ser semelhante a:

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

Neste YAML (hipotético), definimos um agente do tipo bedrock_agent, fornecemos um nome e instruções, especificamos o modelo de base por ID e fornecemos o ARN da função que ele deve usar. Também declaramos algumas ferramentas: uma habilitando o Interpretador de Código interno, outra habilitando a ferramenta de Entrada do Usuário interna e um MenuPlugin personalizado (que seria definido separadamente no código e registrado como uma função kernel). Esse arquivo encapsula a configuração do agente em uma forma legível por humanos.

Para instanciar um agente a partir do YAML, use o carregador estático com a fábrica apropriada. Por exemplo:

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

Isso analisará o YAML e produzirá uma instância BedrockAgent (ou outro tipo com base no campo type) usando o kernel e a fábrica de objetos fornecidos.

O suporte a Especificações Declarativas do BedrockAgent estará disponível em breve.

Recurso atualmente indisponível em Java.