Playbook 参数

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

参数声明

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

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

• 字符串
• 数字
• 布尔值
• 工具专用参数类型

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

输入（读取）参数

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

输入参数是按 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 传递到流，请执行以下操作：

• 在流设置中，定义同名的 输入参数 。
• 在说明和示例中添加参数使用情况。

流到任务 playbook

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

• 在流设置中，定义 返回参数 。
• 在说明和示例中添加参数使用情况。

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

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

日常安排 playbook 到任务 playbook

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

• 为任务 playbook 定义同名的输入参数。
• 在说明和示例中添加参数使用情况。

涉及工具的示例

假设有一个代理专为活动门票销售而设计，并具有以下任务 playbook：

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

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

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

• 具有输入参数 event_id，并指定了一些实际值，每个示例中的值都不同。
• 包含工具使用操作，其请求正文包含与输入参数中指定的实际 event_id 值相同 的值。

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

• 包含用户话语，用户在其中选择具有一些实际 event_id 的活动，每个示例中的值都不同。
• 包含 Ticket ordering 的 playbook 调用，该调用将 event_id 参数设置为与用户选择确定的实际 event_id 相同 的值。

除了添加示例之外，还可以尝试在 说明、 目标或 工具详情 中添加具体说明，解释应如何使用参数。例如，playbook 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 会在请求正文中将相同的 event_id 传递给 Ticket sales API。Playbook 依赖于具有不同参数值的示例来帮助它们推断应如何使用参数。