コードブロック

プレイブックを定義するときに、コードブロック（エージェントの動作をより適切に制御するために使用できるインライン Python コード）を必要に応じて指定できます。このコードは、特別なデコレータを持つ関数と、必要なユーティリティ関数で構成されています。

コードを記述する際に、コードブロック システム ライブラリを使用してエージェントの動作を制御できます。

既知の問題

次の既知の問題があります。

  • Artifact Registry へのアクセスを制限する VPC-SC 境界内のプロジェクトも、コードブロックのデプロイを拒否します。

制限事項

次の制限が適用されます。

  • コードブロックにデータを永続化するオブジェクトを含めることはできません。ただし、ツールを使用してデータを永続化し、状態を維持することはできます。
  • コードブロックはリモート呼び出しを直接行うことはできません。たとえば、Python requests ライブラリは使用できません。ただし、ツールを利用して間接的にリモート呼び出しを行うことはできます。
  • Python 名に変換されるリソース名は、有効な Python 名である必要があります。
  • フローの移行が行われない限り、コードブロックでセッション パラメータを読み書きすることはできません。

インライン アクション

インライン アクションは、ツール アクションと同様に動作します。入力スキーマと出力スキーマが定義されています。これは、型アノテーションや docstring など、Python 関数のシグネチャによって決まります。ツール呼び出しと同様に、LLM はアクションを実装するコードを認識しません。

サンプル:

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

この関数では、LLM にアクション、その入力、出力に関する情報が提供されます。

プレイブックの手順でインライン アクションを参照するには、バッククォートでアクション名を指定し、その使用方法を説明します。

place_order インライン アクションのサンプル:

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

インライン アクションを使用する例を作成するには、[入力と出力] セクションで inline-action ツールタイプを使用します。

詳細については、@Action リファレンス ドキュメントをご覧ください。

関数をトリガーする

トリガー関数は、コードで条件付きアクションを定義するために使用されます。

トリガー関数はデコレータを使用して宣言されます。次のトリガー関数デコレータを使用できます。

デコレータ デコレータ パラメータ 説明
@EventTrigger event: str, condition: str（条件は省略可） イベントによってトリガーされる
@BeforeModelTrigger condition: str（条件は省略可） LLM が次のアクションを予測するたびにトリガーされます。
@BeforeActionTrigger condition: str（条件は省略可） LLM がアクションを実行するたびにトリガーされます。
@BeforePlaybookTrigger condition: str（条件は省略可） ハンドブックが初めて開始されたときにトリガーされます。

たとえば、これらの関数は、これらのデコレータとデコレータ パラメータの使用方法と、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 ☕")

フロー、ハンドブック、ツールの参照

コードブロックでは、flows、playbooks、tools グローバル変数を使用して、特定のフロー、プレイブック、ツールを参照できます。

これらの各オブジェクトには、対応するリソースの名前と一致するメンバーがあります。これらの名前は Python の有効な名前である必要があります。

サンプル:

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

コードブロックでフローとハンドブックを参照する場合は、次の構文を使用して、ハンドブックの手順でも参照する必要があります。

${RESOURCE_TYPE: my_resource_name}

たとえば、コードブロックに flows.myflow と playbooks.myplaybook が含まれている場合、ハンドブックの手順には次の内容を含める必要があります。

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

アクションのオーバーライド

コードブロックを使用すると、LLM によって決定された後続のアクションの前に実行されるアクションのキューを作成し、それらのアクションをオーバーライドできます。アクションのオーバーライドを作成するには、add_override グローバル関数を使用します。

キューに登録されたオーバーライド アクションはすべて順番に実行され、アクションの出力は LLM で使用できます。キューが空になると、オーバーライドによって respond またはターンを完了する別の関数でターンが終了しない限り、オペレーションはアクションと入力の選択のために LLM に戻ります。

関数の引数:

  • action: 実行するアクション。インライン アクションの場合は、my_function_name を使用します。ツール アクションの場合は、tools.my_tool_name.my_tool_action を使用します。フロー アクションの場合は、flows.my_flow_name を使用します。
  • inputs: アクションの省略可能な入力。 例: {"location": "Omaha"}。

サンプル:

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

レスポンスのオーバーライド

アクションのオーバーライドと同様に、エージェントのレスポンスに特化した respond グローバル関数を使用して、エージェントが特定のコンテンツでユーザーに応答するように強制できます。

サンプル:

respond("Hello")

通話ツール

コードブロック関数では、エージェント用に定義されたツールを呼び出すことができます。ツールアクションをオーバーライドする場合とは異なり、ツールを直接呼び出す場合、ツール実行の結果は LLM で使用できません。

サンプル:

# 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"]

インテントを照合する

コードブロックでは、Flow.match_intent 関数を使用して、特定のフローのインテントをプログラムで照合できます。

サンプル:

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

デバッグ

シミュレータを使用して、コードブロック関数のデバッグを行うことができます。これらの関数はシミュレータでアクションとして表示され、必要に応じて詳細を提供します。

追加の制御

このガイドでは、コードブロック システム ライブラリの一般的な使用方法について説明します。他のタイプのコントロールについては、ライブラリのドキュメントをご覧ください。