参数与模板

把值映射到目的地中——来自字段或固定值的参数、必填参数、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.urlURL 编码。密钥按原样插入,因此它可以容纳整个 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 错误——密钥的修改无需部署——但引用它的投递在其设置好之前会失败。参见工作区密钥。

本页内容