コードブロック

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

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

制限事項

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

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

インライン アクション

インライン アクションは、ツール アクションと同様に動作します。これらには、Python 関数のシグネチャ（型アノテーションや docstring など）によって決定される、定義済みの入力スキーマと出力スキーマがあります。ツール呼び出しと同様に、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 のリファレンス ドキュメントをご覧ください。

関数をトリガーする

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

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

Decorator	デコレータ パラメータ	説明
@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 で使用できるようになります。キューが空になると、オペレーションは LLM に戻り、アクションと入力の選択が行われます。ただし、オーバーライドが respond またはターンを完了する別の関数でターンを完了する場合を除きます。

関数の引数:

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

デバッグ

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

その他の管理

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