参数与模板
把值映射到目的地中——来自字段或固定值的参数、必填参数、URL、请求头、请求体和文本中的 {{…}} 变量,以及每个位置如何替你编码它们。
目的地依靠两样工具工作:参数(params),即目的地携带的命名值;以及模板,即你在其 URL、请求头、请求体和文本中编写的 {{…}} 变量。
参数
{
"params": {
"message": { "from": "state.message", "required": true },
"route": { "from": "result.route" },
"lead_score": { "from": "composites.lead_score" },
"team": { "value": "inbound" }
}
}参数的值要么来自本次运行的某个字段(from),要么是一个固定值(value):最多 500 个字符的字符串、数字、true、false 或 null。一个目的地最多有 30 个参数,名称由字母、数字和 _ 组成——最多 48 个字符,不能以数字开头。
来源
from | 值 |
|---|---|
state | 整个状态:对象、字符串或数组。 |
state.<field> | 对象状态 schema 中声明的字段。 |
result.<question> | 回答:选项、级别标签或概率。 |
confidence.<question> | 回答的置信度,0 到 1。 |
scores.<question> | score 问题的加权级别。 |
composites.<key> | 复合指标的值。 |
action | 最终行动:continue、block、escalate 或 fallback。 |
decision.slug | 决策的 slug。 |
decision.version | 作答的版本——在运行草稿的 Playground 中为 null。 |
execution.id | 本次运行的 exec_… ID。 |
值保留其 JSON 类型:confidence.route 是数字,state 是对象。不存在的值——调用方未发送的可选字段、引擎错误 fallback 之后的任何回答——为 null。
必填参数
当目的地缺少某个参数就毫无意义时——没有电子邮箱的 CRM 线索——请把该参数标记为 required。当它解析为 null 或空字符串时,目的地不会触发,响应会说明原因:
{ "key": "create_lead", "type": "http", "status": "skipped", "reason": "missing_param", "param": "email" }参数去往哪里
| 类型 | 参数会…… |
|---|---|
webhook | 在事件中发送,位于 data.params 下。 |
workflow | 作为顶层 JSON 字段发送——n8n、Make 和 Zapier 可以直接映射。 |
http | 对于没有请求体模板的 POST、PUT 和 PATCH 请求,作为 JSON 请求体;对于 URL 中未使用它们的 GET 和 DELETE 请求,作为查询字符串。 |
agent | 在请求体中发送,位于 params 下。 |
function | 作为第一个参数传给你的处理函数。 |
reply、llm | 仅通过其文本中的 {{params.…}} 使用。 |
凡是发往第三方的内容都请使用参数:webhook 或工作流永远不会收到状态本身,只会收到你映射的参数——只发送接收方需要的内容,不多发。
模板
在变量两侧写上 {{ 和 }}——内部允许有空格:{{ params.awb }}。
| 变量 | 值 |
|---|---|
{{params.<name>}} | 此目的地的一个参数。 |
{{state}}、{{state.<field>}} | 状态,或对象状态中声明的字段。 |
{{result.<question>}}、{{confidence.<question>}}、{{scores.<question>}} | 回答、其置信度、加权级别。 |
{{composites.<key>}} | 复合指标的值。 |
{{action}}、{{decision.slug}}、{{decision.version}}、{{execution.id}} | 本次运行。 |
{{delivery.id}} | 此次投递的 dlv_… ID——每次尝试都相同。 |
{{secrets.<NAME>}} | 一个工作区密钥。 |
编辑器中每个字段旁的 插入… 菜单会列出该处可以使用的变量。
编码是自动的
你永远不需要手动转义任何内容:Dcision 会根据值所在的位置对其进行编码。
| 位置 | 值如何插入 | 密钥 |
|---|---|---|
URL——webhook.url、http.url、agent.url、workflow.url | URL 编码。密钥按原样插入,因此它可以容纳整个 URL。 | 允许 |
请求头的值——http.headers、agent.headers | 作为文本,换行符替换为空格——值无法添加请求头。 | 允许 |
http.body | 作为 JSON——见下文。 | 允许 |
文本——reply.text、reply.buttons、llm.instructions、llm.input、agent.instructions | 作为文本,保留换行。 | 不允许:文本会返回给调用方或发送给模型。 |
作为文本插入时,字符串按原样插入,数字和布尔值会被打印出来,对象和数组变成 JSON,null 变成空字符串。
JSON 请求体
http 请求体模板是带变量的 JSON,变量所在的位置决定它的写法:
- 在引号外,它会变成一个 JSON 值——带引号的字符串、数字、
true、null、对象。 - 在引号内,它会变成该字符串内部的文本,并按需转义。
对于一个对象状态具有 email 和 company_size 字段、并有一个取自 state.email 的参数 email 的决策:
{
"email": {{params.email}},
"company_size": {{state.company_size}},
"summary": "Route {{result.route}} at {{confidence.route}} — lead score {{composites.lead_score}}",
"lead": {{state}}
}{
"email": "ana@acme.com",
"company_size": 500,
"summary": "Route sales at 0.85 — lead score 0.8414",
"lead": { "message": "We need pricing for 500 users.", "email": "ana@acme.com", "company_size": 500 }
}所以要写 {{state.company_size}}——而不是 "{{state.company_size}}"——才能发送数字 500 而不是文本 "500"。{{params.email}} 也不需要引号:它的值是字符串,因此会连同引号一起写入。
填入变量后,请求体必须是有效的 JSON:保存时编辑器会用示例值检查它,无效的模板会被拒绝,并提示 "The body must be JSON once variables are filled in…"。请求体最多 10,000 个字符。在 POST、PUT 和 PATCH 上留空,即可把参数作为 JSON 对象发送;GET 和 DELETE 请求没有请求体。
模板检查
模板会在你保存或部署时进行校验:
- 每个变量都必须存在:
{{params.awb}}需要一个名为awb的参数,{{state.company_size}}需要对象状态中的一个字段,{{result.route}}需要一个名为route的问题; - 密钥名称使用 UPPER_SNAKE_CASE,例如
{{secrets.CRM_TOKEN}}; - 每个
{{都需要对应的}},内部只有一个变量; - 密钥不能在文本中使用。
缺失的密钥不是 schema 错误——密钥的修改无需部署——但引用它的投递在其设置好之前会失败。参见工作区密钥。