代码块

定义 playbook 时， 您可以选择提供 代码块， 这些代码块是内嵌 Python 代码，可用于更好地控制智能体行为。 此代码由带有特殊修饰符的函数以及您需要的任何实用程序函数组成。

编写代码时， 您可以使用 代码块系统库 来控制智能体行为。

限制

存在以下限制：

• 代码块不能包含任何会保留数据的对象。 不过，您可以使用工具来保留数据和维护状态。
• 代码块不能直接进行远程调用。例如，您不能使用 Python requests 库。 不过，您可以利用工具间接进行远程调用。
• 转换为 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 提供有关操作、其输入和输出的信息。

如需在 playbook 说明中引用内嵌操作，只需在反引号中引用操作名称，并说明应如何使用该操作。

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 是可选的	首次启动 playbook 时触发。

例如，这些函数展示了如何使用这些修饰符和 修饰符参数，以及如何使用 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 ☕")

引用流、playbook 和工具

在代码块中，您可以使用特定的流、playbook 和工具 使用 flows、 playbooks和 tools 全局变量。

这些对象中的每一个都有与相应资源名称匹配的成员。 这些名称必须是 合法的 Python 名称。

示例：

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

在代码块中引用流和 playbook 时，您还必须使用以下语法在 playbook 说明中引用它们：

${RESOURCE_TYPE: my_resource_name}

例如，如果您的代码块包含 flows.myflow 和 playbooks.myplaybook，则您的 playbook 说明应包含：

${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"]

匹配 intent

代码块可以使用给定流的 intent 以编程方式匹配 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"]

调试

您可以使用模拟器调试代码块函数。 这些函数将在模拟器中显示为操作，并根据需要提供详细信息。

其他控制项

本指南介绍了 代码块系统库的一些常见用途。 如需了解其他类型的控制，请参阅库文档。