Playbook 参数

剧本可以使用明确定义的参数接受和发出上下文信息。参数用于存储有关对话的信息，例如用户选择、操作结果等。 您可以在 playbook 和流程之间传递这些参数的值。

参数声明

您可以定义输入（读取）参数和输出（写入）参数。

参数具有名称、说明和以下类型之一：

• 字符串
• 数字
• 布尔值
• 特定于工具的参数类型

您还可以指定参数是否为列表。

输入（读取）参数

对于每个 playbook，您都可以定义输入参数（也称为读取参数），以便 playbook 使用从流程和其他 playbook 传递的值。例如，某个 playbook 可能会收到用户的首选名称作为参数，并使用该名称来亲自感谢用户；或者，它可能会收到订单标识符作为参数，并使用该标识符通过 tool 检索订单详情。

输入参数是按 playbook 定义的，并且 playbook 默认情况下无法查看其他 Dialogflow CX 控制台参数类型。当流程转换到剧本时，如果目标剧本具有同名的输入参数，则页面和会话参数会传播到该剧本。如需在转换期间将信息从流程传递到剧本，请定义与转换之前存在的会话或页面参数名称相同的剧本输入参数。

注意： 默认 playbook 不接受输入参数。默认剧本充当用户对话的入口点，因此无法接收输入参数。

创建示例来控制输入参数值应如何影响操作。 例如，如果输入参数应影响代理指代用户的方式，请创建一些示例，这些示例定义了参数的值，然后在示例中的话语操作中使用相同的值。如需了解详情，请参阅传递参数。

输出（写入、返回）参数

对于每个 playbook，您都可以定义输出参数（也称为写入参数和返回参数），以便 playbook 发出可供其他流程或 playbook 使用的信息。例如，一个 playbook 可能会从用户那里收集订单号，并通过输出参数发出该订单号；或者，一个 playbook 可能会使用工具预订航班，并通过输出参数发出确认编号。

创建示例以控制 playbook 应如何确定每个输出形参的值。 例如，如果表示确认编号的输出参数应从工具使用的输出中派生其值，请创建工具使用的输出与 playbook 输出参数的值相匹配的示例。

传递参数

注意： 任务 playbook 无法调用常规 playbook，因此下文未介绍参数传递场景。

与流程不同，Playbook 不支持使用特定语法注入参数值。相反，剧本会依赖指令和少样本提示示例来确定如何使用参数值，以及在指定参数值时应如何确定值。

从日常安排 playbook 到流程

如需将参数从常规 playbook 传递到流，请执行以下操作：

• 为常规剧本定义写入参数。 这些参数将成为会话参数。
• 流程可以利用会话参数。
• 在说明和示例中添加了参数用法。

日常安排 playbook 的流程

如需将参数从流传递到例程 playbook，请执行以下操作：

• 流写入会话参数。
• 为同名例程 playbook 定义读取参数。
• 在说明和示例中添加了参数用法。

任务 playbook 到流程

如需将参数从任务 playbook 传递到流，请执行以下操作：

• 在流程设置中，定义名称相同的输入参数。
• 在说明和示例中添加了参数用法。

从流程到任务 playbook

如需将参数从流传递到父任务 playbook，请执行以下操作：

• 在流程设置中，定义返回参数。
• 在说明和示例中添加了参数用法。

如需将参数从流传递到子任务 playbook，请执行以下操作：

• 定义与流程中的会话参数同名的任务输入参数。
• 在说明和示例中添加了参数用法。

从日常安排 playbook 到任务 playbook

如需将参数从常规 playbook 传递到任务 playbook，请执行以下操作：

• 为具有相同名称的任务 playbook 定义输入参数。
• 在说明和示例中添加了参数用法。

涉及工具的示例

假设有一个专为活动门票销售设计的代理，其任务剧本如下：

1. 一个名为 Ticket ordering 的 playbook，该 playbook 使用名为 Ticket sales API 的工具下单。
   1. 此 playbook 接受一个类型为 number 且名称为 event_id 的输入参数。
   2. Ticket sales API 工具需要包含 event_id 的请求。
2. 一个名为 Event selection 的剧本，可帮助用户选择活动，然后通过参数 event_id 将用户引导至 Ticket ordering 以购买门票。

在此示例中，为确保 event_id 可靠地从 Event selection 传递到 Ticket ordering，并从 Ticket ordering 传递到 Ticket sales API，需要多个示例。

Ticket ordering 剧本应包含多个示例，这些示例：

• 输入参数 event_id 指定为某个实际值，每个示例中的值各不相同。
• 在请求正文中添加工具使用操作，其中包含与输入参数中指定的相同的实际 event_id 值。

Event selection 剧本应包含多个示例，这些示例：

• 包含用户话语，其中用户选择了一个具有一些实际 event_id 的事件，每个示例中的 event_id 各不相同。
• 包含对 Ticket ordering 的 playbook 调用，该调用将 event_id 参数设置为用户选择的相同的实际 event_id。

除了添加示例之外，还可以尝试在说明、目标或工具详情中添加具体说明，解释如何使用参数。例如，操作手册 Ticket ordering 包含以下指令：

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

在上述示例和说明的帮助下，Event selection playbook 可以根据用户的选择正确决定 event_id，并将其作为名为 event_id 的输入形参传递给 Ticket ordering playbook。然后，Ticket ordering 在向 Ticket sales API 发出的请求的正文中传递相同的 event_id。Playbook 依赖于具有不同形参值的示例，以帮助推断形参应如何使用。