Blocs de code

Lorsque vous définissez un playbook, vous pouvez éventuellement fournir des blocs de code, qui sont du code Python intégré pouvant être utilisé pour mieux contrôler le comportement de l'agent. Ce code est constitué de fonctions avec des décorateurs spéciaux et de toutes les fonctions utilitaires dont vous avez besoin.

Lorsque vous écrivez votre code, vous pouvez utiliser la bibliothèque système de blocs de code pour contrôler le comportement de l'agent.

Problèmes connus

Les problèmes connus suivants s'appliquent :

• Les projets situés dans des périmètres VPC-SC qui restreignent l'accès à Artifact Registry refuseront également les déploiements de blocs de code.

Limites

Les limites suivantes s'appliquent :

• Les blocs de code ne peuvent pas contenir d'objets qui conservent des données. Toutefois, vous pouvez utiliser des outils pour conserver les données et maintenir l'état.
• Les blocs de code ne peuvent pas effectuer d'appels à distance directement. Par exemple, vous ne pouvez pas utiliser la bibliothèque Python "requests". Toutefois, vous pouvez utiliser des outils pour passer des appels à distance indirectement.
• Les noms de ressources convertis en noms Python doivent être des noms Python valides.
• Les blocs de code ne peuvent pas lire ni écrire de paramètres de session, sauf si une transition de flux a lieu.

Actions intégrées

Les actions intégrées se comportent de la même manière que les actions d'outil. Ils disposent d'un schéma d'entrée et de sortie défini, qui est déterminé par la signature de la fonction Python, y compris les annotations de type et la docstring. Comme pour les appels d'outils, le LLM n'a pas connaissance du code qui implémente l'action.

Exemple :

@Action
def is_prime(n: int): bool
  """Returns true if n is prime."""
  import math
  return (all([False for i in range(2, math.sqrt(n)
               if n % i == 0 ]) and not n < 2)

Pour cette fonction, le LLM recevra des informations sur l'action, son entrée et sa sortie.

Pour faire référence à une action intégrée dans les instructions de votre playbook, il vous suffit de mentionner le nom de l'action entre guillemets inversés et de décrire comment l'utiliser.

Exemple d'action intégrée place_order :

Take the customer's order, then call the `place_order` action when the order is ready.

Pour créer des exemples qui utilisent des actions intégrées, utilisez le type d'outil inline-action dans la section Entrée et sortie.

Pour en savoir plus, consultez la documentation de référence @Action.

Déclencher des fonctions

Les fonctions de déclenchement sont utilisées pour définir des actions conditionnelles dans le code.

Les fonctions de déclencheur sont déclarées à l'aide de décorateurs. Vous pouvez utiliser les décorateurs de fonction de déclencheur suivants :

Par exemple, ces fonctions montrent comment utiliser ces décorateurs et paramètres de décorateur, ainsi que la fonction de bibliothèque système de bloc de code respond.

# No decorator parameter
@PlaybookStartTrigger
def my_playbook_conditional_action():
  respond("How can I help?")

# With a condition decorator parameter
@BeforeActionTrigger('$next-action.name = "search"')
def my_before_action_conditional_action():
  respond("One moment please")

# Event
@EventTrigger(event="welcome")
def my_welcome_event():
  respond("hi")

# Event with a condition:
@EventTrigger(event="welcome",
              condition="$sys.func.NOW().hours < 10")
def my_good_morning_event():
  respond("Good morning ☕")

Référencer des flux, des playbooks et des outils

Dans votre bloc de code, vous pouvez faire référence à des flux, des playbooks et des outils spécifiques à l'aide des variables globales flows, playbooks et tools.

Chacun de ces objets comporte des membres dont les noms correspondent à ceux des ressources correspondantes. Ces noms doivent être des noms Python valides.

Exemple :

  add_override(playbooks.troubleshooting, {})
  add_override(flows.billing)
  add_override(tools.weather_api.get_weather, {"location": "San Francisco"})

Lorsque vous référencez des flux et des playbooks dans un bloc de code, vous devez également les référencer dans les instructions du playbook avec la syntaxe suivante :

${RESOURCE_TYPE: my_resource_name}

Par exemple, si votre bloc de code contient flows.myflow et playbooks.myplaybook, les instructions de votre playbook doivent inclure les éléments suivants :

${FLOW: myflow}
${PLAYBOOK: myplaybook}

Remplacements d'actions

Vous pouvez utiliser des blocs de code pour créer une file d'attente d'actions qui auront lieu avant toute autre action déterminée par le LLM, et potentiellement les remplacer. Vous créez des remplacements d'action à l'aide de la fonction globale add_override.

Toutes les actions de remplacement mises en file d'attente seront exécutées séquentiellement, et le résultat de l'action sera disponible pour le LLM. Une fois la file d'attente vide, l'opération revient au LLM pour la sélection d'actions et d'entrées, sauf si un remplacement termine le tour avec respond ou une autre fonction qui termine le tour.

Arguments de la fonction :

• action : action à effectuer. Pour une action intégrée, utilisez my_function_name. Pour une action d'outil, utilisez tools.my_tool_name.my_tool_action. Pour une action de flux, utilisez flows.my_flow_name.
• inputs : entrées facultatives pour l'action. Exemple : {"location": "Omaha"}.

Exemples :

# Assuming remote tool named "dmv" with operationId "search_offices"
# remote tool with only requestBody
add_override(tools.dmv.search_offices,{"address": "95030"})

# remote tool with only parameters
add_override(tools.pets.get_pet, {"id": "123"})

# remote tool with requestBody + parameters:
add_override(tools.pets.create_pet, {"requestBody": {"arg1":"foo"}, "param1": "bar"})

# datastore. Assumes existing datastore tool named "Menu".
add_override(tools.menu.Menu, {"query": "what is the menu"})

# code block action. Assumes another code block @Action my_action.
add_override(my_action)

Remplacements des réponses

Comme pour les remplacements d'actions, mais spécifiquement pour les réponses de l'agent, vous pouvez utiliser la fonction globale respond pour forcer l'agent à répondre à l'utilisateur avec un contenu spécifique.

Exemple :

respond("Hello")

Outils d'appel

Dans vos fonctions de bloc de code, vous pouvez appeler les outils définis pour votre agent. Contrairement à ce qui se passe lorsque vous remplacez une action d'outil, lorsque vous appelez un outil directement, les résultats de l'exécution de l'outil ne sont pas disponibles pour le LLM.

Exemples :

# Assumes existing tool named "DMV" with operationId "search_offices"
# remote tool with only request body.
offices = tools.dmv.search_offices({"address": "95030"})

# remote tool with parameters and request body
offices = tools.dmv.search_offices({"requestBody": {"address":"95030"}, "param1":"foo"})

# datastore actions. Assumes existing datastore tool named "Menu".
data = tools.menu.Menu({"query": "get the menu"})["snippets"]

Correspondance de l'intention

Les blocs de code peuvent faire correspondre de manière programmatique une intention pour un flux donné à l'aide de la fonction Flow.match_intent.

Exemple :

matches = flows.flow1.match_intent(history.last_user_utterance).matches
if matches and matches[0].intent == "some_intent":
  to_country = matches[0].parameters.get("to_country")
  if to_country:
    respond(f"To confirm, you're going to {to_country}, right?")

Débogage

Vous pouvez utiliser le simulateur pour déboguer les fonctions de bloc de code. Ces fonctions seront affichées sous forme d'actions dans le simulateur et fourniront nos informations si nécessaire.

Contrôle supplémentaire

Ce guide couvre certaines utilisations courantes de la bibliothèque système de blocs de code. Pour découvrir d'autres types de contrôles, consultez la documentation de la bibliothèque.