Exploration du noyau sémantique BedrockAgent

La documentation de l’API BedrockAgent sera bientôt disponible.

La documentation de l’API BedrockAgent sera bientôt disponible.

Fonctionnalité actuellement indisponible en Java.

Ajoutez le package Agents Bedrock du Semantic Kernel à votre projet .NET :

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

Cela apportera la prise en charge du SDK de noyau sémantique pour Bedrock, y compris les dépendances de l'AWS SDK pour Bedrock. Vous devrez peut-être également configurer les informations d’identification AWS (par exemple, via des variables d’environnement ou la configuration AWS par défaut). Le Kit de développement logiciel (SDK) AWS utilisera vos informations d'identification configurées ; assurez-vous d'avoir votre AWS_ACCESS_KEY_ID, votre AWS_SECRET_ACCESS_KEY, et votre région par défaut définis dans votre environnement ou votre profil AWS. (Pour plus d’informations, consultez la documentation d’AWS sur la configuration des informations d’identification.)

Installez le package de noyau sémantique avec les extras AWS :

pip install semantic-kernel[aws]

Cela garantit que les bibliothèques AWS nécessaires (par exemple, boto3) sont installées en même temps que le noyau sémantique. Avant d’utiliser un agent Bedrock en Python, vérifiez que vos informations d’identification et région AWS sont correctement configurées (par exemple, en définissant des variables d’environnement ou en utilisant AWS CLI). Vous devez avoir les AWS_ACCESS_KEY_ID, les AWS_SECRET_ACCESS_KEY, et les AWS_DEFAULT_REGION (ou profil AWS) définis pour que boto3 puisse s’authentifier.

Fonctionnalité actuellement indisponible 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);

Dans le code ci-dessus, nous utilisons d’abord le Kit de développement logiciel (SDK) AWS (AmazonBedrockClient) pour créer un agent sur Bedrock, en spécifiant le modèle de base, un nom, les instructions et l’ARN du rôle IAM que l’agent doit supposer. Le service Bedrock répond avec une définition d’agent (y compris un AgentId unique). Nous appelons ensuite PrepareAgentAsync pour faire passer l'agent à un état prêt (l'agent passera d'un état CREATING à NOT_PREPARED, puis à PRÉPARÉ une fois prêt). Enfin, nous construisons un BedrockAgent objet à l’aide de la définition retournée et des clients AWS. Cette BedrockAgent instance est ce que nous allons utiliser pour envoyer des messages et recevoir des réponses.

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

Dans l’exemple ci-dessus, BedrockAgent.create_and_prepare_agent gère le flux de création complet : il utilise votre configuration AWS (via boto3) pour créer un agent sur Bedrock avec le nom donné, le modèle de base et les instructions, puis attend automatiquement que l’agent atteigne un état prêt (en effectuant l’étape de préparation en interne). Le résultat est une BedrockAgent instance prête à être utilisée. Sous le capot, cette méthode crée des clients AWS (pour Bedrock et Bedrock Runtime) à l’aide de vos informations d’identification par défaut. Vérifiez donc que votre environnement AWS est configuré. Si vous avez besoin d’une configuration personnalisée, vous pouvez également construire manuellement les clients AWS et les transmettre en tant que paramètres (par exemple client= boto3.client("bedrock") , et runtime_client= boto3.client("bedrock-runtime")) à l’appel create_and_prepare_agent .

Fonctionnalité actuellement indisponible en Java.

Pour .NET, l’identificateur de l’agent Bedrock est une chaîne accessible via agent.Id. Pour récupérer un agent existant par ID, utilisez le client AWS Bedrock, puis construisez un nouveau BedrockAgent:

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

Ici, nous appelons GetAgentAsync sur le client IAmazonBedrock avec l’ID connu, ce qui retourne la définition de l’agent (nom, modèle, instructions, etc.). Nous initialisons ensuite un nouveau BedrockAgent avec cette définition et les mêmes clients. Cette instance de l’agent sera liée à l’agent Bedrock existant.

En Python, vous pouvez récupérer un agent par ID à l’aide du client AWS Bedrock boto3, puis l’encapsuler dans un 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"])

Dans cet extrait de code, nous utilisons boto3 pour appeler get_agent sur le service Bedrock (en l'exécutant dans un thread via asyncio.to_thread, car boto3 est bloquant). Le retour agent_info["agent"] contient les détails de l’agent (id, nom, état, etc.), que nous transmettons au constructeur BedrockAgent. Étant donné que nous n’avons pas fourni explicitement de clients AWS, BedrockAgentil crée en interne de nouveaux clients avec des paramètres par défaut. (Si vous le souhaitez, vous pouvez fournir client= et runtime_client= pour réutiliser des clients si vous les avez.)

Fonctionnalité actuellement indisponible en Java.

Les spécificités du thread de l’agent Bedrock sont abstraites par la BedrockAgentThread classe (qui implémente l’interface commune AgentThread ). Actuellement, le BedrockAgent prend uniquement en charge les fils de type 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 });
}

Dans cet exemple, nous créons explicitement un BedrockAgentThread (en passant le runtimeClient, qu’il utilise pour communiquer avec le service d’exécution Bedrock). Nous appelons ensuite agent.InvokeAsync(...) avec un ChatMessageContent qui représente le message d'un utilisateur. InvokeAsync retourne un flux asynchrone de réponses : dans la pratique, un Agent Bedrock retourne généralement une réponse finale par appel (étant donné que les actions d’outil intermédiaires sont gérées séparément), vous obtiendrez généralement une seule réponse ChatMessageContent à partir de la boucle. Nous affichons la réponse de l’assistant (response.Content). Dans le bloc final, nous supprimons le thread, qui met fin à la session Bedrock sur AWS. Nous supprimons également l’agent lui-même dans ce cas (puisque nous l’avons créé uniquement pour cet exemple) : cette étape est facultative et uniquement nécessaire si vous n’avez pas l’intention de réutiliser à nouveau l’agent (voir Suppression d’un BedrockAgent ci-dessous).

Vous pouvez continuer une conversation existante en réutilisant le même agentThread pour les appels suivants. Par exemple, vous pouvez effectuer une boucle de lecture d’entrée utilisateur et appeler InvokeAsync chaque fois avec le même thread pour poursuivre un dialogue à plusieurs tour. Vous pouvez également créer un BedrockAgentThread avec un ID de session connu pour reprendre une conversation enregistrée précédemment :

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

L’utilisation d’un agent Bedrock dans Python est similaire, avec BedrockAgentThread gérant la session. Vous pouvez démarrer un nouveau thread ou passer un thread existant pour poursuivre une conversation :

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

Dans ce code, nous parcourons quelques entrées utilisateur. Sur chaque itération, nous appelons agent.get_response(...) avec le message utilisateur et le thread actuel. Le premier appel démarre la session Bedrock et retourne une AgentResponseItem (ou ChatMessageContent) contenant la réponse de l’assistant. Nous imprimons la réponse, puis récupérons le response.thread – qui est le même BedrockAgentThread mis à jour avec le nouveau contexte de message – à utiliser pour le tour suivant. Après la conversation (dans cet exemple, deux tours), nous supprimons le thread pour mettre fin à la session sur AWS.

Si vous omettez le thread paramètre dans l’appel, agent.get_response ou agent.invoke créez automatiquement un thread pour cet appel et incluez-le dans la réponse.

Vous avez également la possibilité d'envoyer un lot de messages en une seule fois en passant une liste de messages à get_response ou en utilisant l'invocation de diffusion en continu asynchrone. Par exemple, pour diffuser en continu la réponse de l’Assistant (jeton par jeton) pour une seule requête :

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

La invoke_stream(...) méthode génère des ChatMessageContent objets à mesure que la réponse est générée. En itérant dessus, vous pouvez générer la réponse de l’Assistant de manière incrémentielle (ici, nous affichons des caractères sans nouvelle ligne pour former la réponse complète).

Fonctionnalité actuellement indisponible en Java.

Utilisez le client Bedrock pour supprimer par ID d’agent. Par exemple:

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

Après cet appel, l’état de l’agent change et ne sera plus utilisable. (Toute tentative d’appel d’un agent supprimé entraîne une erreur.)

Appelez la méthode de suppression de l’agent. Par exemple:

await agent.delete_agent()

Cela appelle le service Bedrock pour supprimer l’agent (et marquer en interne l’objet BedrockAgent comme supprimé). Vous pouvez vérifier en utilisant agent.id ou un indicateur s’il est fourni (par exemple, _is_deleted).

Fonctionnalité actuellement indisponible 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()

Dans ce code, chaque fois que l’agent doit appeler une fonction à partir MenuPlugin (par exemple, get_specials ou get_item_price), le handle_intermediate_steps rappel affiche une ligne pour l’appel de fonction et un autre pour le résultat de la fonction. La réponse de l’Assistant final pour chaque requête utilisateur est ensuite imprimée normalement. En observant le contenu intermédiaire, vous pouvez suivre la façon dont l’agent est arrivé à sa réponse (quel outil a été utilisé, ce qu’il a retourné, etc.).

Par exemple, la sortie peut ressembler à ceci :

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

Dans l’interaction ci-dessus, les empreintes intermédiaires montrent que l’agent a correctement appelé MenuPlugin.get_specials et MenuPlugin.get_item_price aux moments appropriés, et a utilisé leurs résultats pour répondre à l’utilisateur. Ces détails intermédiaires peuvent être enregistrés ou utilisés dans votre logique d’application en fonction des besoins (par exemple, pour afficher les étapes effectuées par l’agent).

La prise en charge des rappels pour les messages intermédiaires dans BedrockAgent (C#) suit un modèle similaire, mais l’API exacte est en cours de développement. (Les futures versions permettront d’inscrire un délégué pour gérer FunctionCallContent et FunctionResultContent pendant InvokeAsync.)

Fonctionnalité actuellement indisponible en Java.

L’utilisation d’une spécification déclarative peut simplifier la configuration, en particulier si vous souhaitez facilement changer d’installation d’agent ou utiliser une approche de fichier de configuration. Pour un agent Bedrock, une définition YAML peut ressembler à ceci :

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

Dans ce YAML (hypothétique) nous définissons un agent de type bedrock_agent, lui donnez un nom et des instructions, spécifiez le modèle de base par ID et fournissez l’ARN du rôle qu’il doit utiliser. Nous déclarons également quelques outils : l’un activant l’interpréteur de code intégré, un autre permettant l’outil d’entrée utilisateur intégré et un MenuPlugin personnalisé (qui serait défini séparément dans le code et inscrit en tant que fonction noyau). Un tel fichier encapsule la configuration de l’agent dans un formulaire lisible par l’homme.

Pour instancier un agent à partir de YAML, utilisez le chargeur statique avec un patron de création approprié. Par exemple:

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

Cela analysera le YAML et produira une instance BedrockAgent (ou un autre type basé sur le champ type) en utilisant le noyau et la fabrique fournis.

La gestion des spécifications déclaratives de BedrockAgent sera bientôt disponible.

Fonctionnalité actuellement indisponible en Java.