コードブロック

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

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

制限事項

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

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

インライン アクション

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

サンプル:

@Action
def is_prime(n: int) -> bool:
  """Returns true if n is prime."""
  if not isinstance(n, int) or n < 2:
    return False

  for i in range(2, int(n ** 0.5) + 1):
    if n % i == 0:
      return False

  return True

この関数では、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。condition は省略可	イベントによってトリガーされる
@BeforeModelTrigger	condition: str。condition は省略可	LLM が次のアクションを予測するたびにトリガーされる。
@BeforeActionTrigger	condition: str。condition は省略可	LLM がアクションを実行するたびにトリガーされる。
@BeforePlaybookTrigger	condition: str。condition は省略可	ハンドブックが最初に開始されたときにトリガーされる。

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

セッション パラメータの読み取り

コードブロックは、パラメータを読み取ることができます。

サンプル:

state["$session.params.my-param"]
state["$request.session-id"]

デバッグ

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

その他の制御

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