コードブロック

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

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

制限事項

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

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

インライン アクション

インライン アクションは、ツール アクションと同様に動作します。これらには、定義済みの入力スキーマと出力スキーマがあります。これらは、型アノテーションや docstring などの 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, and 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 またはターンを完了する別の関数でターンを完了する場合を除きます。

関数の引数:

• アクション: 実行するアクションを指定します。インライン アクションの場合は、my_function_name を使用します。ツール アクションの場合は、tools.my_tool_name.my_tool_action を使用します。フロー アクションの場合は、flows.my_flow_name を使用します。
• 入力: アクションのオプション入力（{"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"]

デバッグ

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

その他の管理機能

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