Explorando o Kernel Semântico BedrockAgent

Documentação da API do BedrockAgent em breve.

Documentação da API do BedrockAgent em breve.

Recurso atualmente indisponível em Java.

Adicione o pacote Semantic Kernel Bedrock Agents ao seu projeto .NET:

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

Isto trará o suporte do SDK do Kernel semântico para o Bedrock, incluindo dependências no SDK da AWS para o Bedrock. Também pode ser necessário configurar as credenciais da AWS (por exemplo, por meio de variáveis de ambiente ou da configuração padrão da AWS). O AWS SDK usará suas credenciais configuradas; certifique-se de ter seu AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYe região padrão definida em seu ambiente ou perfil da AWS. (Consulte a documentação da AWS sobre configuração de credenciais para obter mais detalhes.)

Instale o pacote Semantic Kernel com os extras da AWS:

pip install semantic-kernel[aws]

Isso garante que as bibliotecas necessárias da AWS (por exemplo, boto3) sejam instaladas junto com o Semantic Kernel. Antes de usar um Bedrock Agent em Python, verifique se suas credenciais e região da AWS estão configuradas corretamente (por exemplo, definindo variáveis de ambiente ou usando a AWS CLI). Você deve ter AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, e AWS_DEFAULT_REGION (ou perfil da 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 AWS SDK (AmazonBedrockClient) para criar um agente no Bedrock, especificando o modelo de fundação, um nome, as instruções e o ARN da função do IAM que o agente deve assumir. O serviço Bedrock responde com uma definição de agente (incluindo um AgentId exclusivo). Em seguida, chamamos PrepareAgentAsync para fazer a transição do agente para um estado pronto (o agente passará de um status CRIANDO para NÃO_PREPARADO e, em seguida, para PREPARADO quando estiver pronto). Por fim, construímos um BedrockAgent objeto usando a definição retornada e os clientes da AWS. Esta 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 sua configuração da AWS (via boto3) para criar um agente no Bedrock com o nome fornecido, o modelo de fundação e as instruções e, em seguida, aguarda automaticamente que o agente atinja um estado pronto (executando a etapa de preparação internamente). O resultado é uma BedrockAgent instância pronta para uso. Nos bastidores, esse método está criando clientes da AWS (para Bedrock e Bedrock Runtime) usando suas credenciais padrão, portanto, garanta que seu ambiente da AWS esteja configurado. Se precisar de uma configuração personalizada, você também pode construir manualmente os clientes da 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 via agent.Id. Para recuperar um agente existente por ID, use o cliente AWS Bedrock e 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, executamos GetAgentAsync no cliente IAmazonBedrock usando o ID conhecido, o que retorna a descrição do agente (nome, modelo, instruções, etc.). Em seguida, inicializamos um novo BedrockAgent com essa definição e os mesmos clientes. Esta instância do agente será ligada ao agente Bedrock existente.

No Python, você também pode recuperar um agente por ID usando o cliente boto3 do AWS Bedrock e, em seguida, envolvê-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 numa thread via asyncio.to_thread já que boto3 está a bloquear). O agent_info["agent"] retornado contém os detalhes do agente (id, nome, estado, etc.), que passamos para o construtor BedrockAgent. Como não fornecemos explicitamente clientes da AWS para a BedrockAgent, ela criará internamente novos clientes com configurações padrão. (Opcionalmente, poderá 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 abstraídas pela classe BedrockAgentThread (que implementa a interface comum AgentThread). Atualmente, o BedrockAgent suporta apenas tópicos 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 usa para se comunicar com o serviço de tempo de execução Bedrock). Em seguida, chamamos agent.InvokeAsync(...) com um ChatMessageContent que representa a mensagem de um utilizador. InvokeAsync retorna um fluxo assíncrono de respostas – na prática, um Agente Bedrock normalmente retorna uma resposta final por invocação (já que as ações da ferramenta intermediária são tratadas separadamente), então você geralmente obterá uma única ChatMessageContent do loop. Imprimimos a resposta do assistente (response.Content). No bloco final, excluímos o thread, que encerra a sessão do Bedrock na AWS. Também excluímos o próprio agente neste caso (já que o criamos apenas para este exemplo) – esta etapa é opcional e só é necessária se você não pretende reutilizar o agente novamente (consulte Excluindo um BedrockAgent abaixo).

Você pode continuar uma conversa existente reutilizando a mesma agentThread para chamadas subsequentes. Por exemplo, você pode fazer 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

Usar um Agente Bedrock em Python é semelhante, com o BedrockAgentThread a gerir a sessão. Você pode iniciar um novo tópico 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

Neste código, fazemos um loop através de algumas entradas do 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) contendo a resposta do assistente. Imprimimos a resposta e, em seguida, pegamos a response.thread – que é a mesma BedrockAgentThread atualizada com o novo contexto da mensagem – para usar no próximo turno. Após a conversa (neste exemplo, duas voltas), excluímos o thread para encerrar a sessão na 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 chamada de streaming assíncrona. Por exemplo, para efetuar o streaming da resposta do assistente (token por token) para um único comando:

# 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 produzir 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 de agente. Por exemplo:

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

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

Chame o método de eliminaçã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). Pode confirmar através de agent.id ou de um indicador, caso fornecido (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()

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

Por exemplo, a saída pode ser:

# 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 sucesso e MenuPlugin.get_item_price nos momentos 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 executadas pelo agente).

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 registrar 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 se parecer com:

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 (hipotético) YAML, definimos um agente do tipo bedrock_agent, damos-lhe um nome e instruções, especificamos o modelo de fundação 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 integrado, outra habilitando a ferramenta de entrada de usuário integrada e um MenuPlugin personalizado (que seria definido separadamente no código e registrado como uma função do kernel). Esse arquivo encapsula a configuração do agente em um formato legível por humanos.

Para instanciar um agente a partir do YAML, use o carregador estático com uma fábrica adequada. 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 fará o parse do YAML e produzirá uma instância BedrockAgent (ou outro tipo baseado no campo type) usando o kernel e a factory fornecidos.

O tratamento de especificações declarativas do BedrockAgent estará disponível em breve.

Recurso atualmente indisponível em Java.