Параметры и шаблоны
Передача значений в назначение — параметры из поля или фиксированного значения, обязательные параметры, переменные {{…}} в 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: объект, строка или массив. |
state.<field> | Поле, объявленное в схеме объектного state. |
result.<question> | Ответ: вариант, метка уровня или вероятность. |
confidence.<question> | Уверенность ответа, от 0 до 1. |
scores.<question> | Взвешенный уровень вопроса score. |
composites.<key> | Значение композита. |
action | Итоговое действие: continue, block, escalate или fallback. |
decision.slug | Slug решения. |
decision.version | Версия, которая ответила, — null в Playground, который выполняет черновик. |
execution.id | ID запуска exec_…. |
Значения сохраняют свой JSON-тип: confidence.route — число, state — объект. Несуществующее значение — необязательное поле, которое вызывающая сторона не отправила, любой ответ после fallback при ошибке движка — равно null.
Обязательные параметры
Помечайте параметр как required, когда назначение без него не имеет смысла, — лид в CRM без e-mail. Когда он разрешается в null или пустую строку, назначение не срабатывает, а ответ объясняет почему:
{ "key": "create_lead", "type": "http", "status": "skipped", "reason": "missing_param", "param": "email" }Куда попадают параметры
| Тип | Параметры… |
|---|---|
webhook | отправляются в событии, в data.params. |
workflow | отправляются как JSON-поля верхнего уровня — то, что n8n, Make и Zapier сопоставляют напрямую. |
http | становятся JSON-телом запросов POST, PUT и PATCH без шаблона тела и строкой запроса для GET и DELETE, если URL их не использует. |
agent | отправляются в теле запроса, в params. |
function | передаются вашему обработчику первым аргументом. |
reply, llm | используются только через {{params.…}} в их текстах. |
Используйте параметры для всего, что попадает к третьей стороне: вебхук или workflow никогда не получают сам state, только сопоставленные вами параметры — отправляйте то, что нужно получателю, и ничего больше.
Шаблоны
Оберните переменную в {{ и }} — пробелы внутри допускаются: {{ params.awb }}.
| Переменная | Значение |
|---|---|
{{params.<name>}} | Параметр этого назначения. |
{{state}}, {{state.<field>}} | State или объявленное поле объектного state. |
{{result.<question>}}, {{confidence.<question>}}, {{scores.<question>}} | Ответ, его уверенность, взвешенный уровень. |
{{composites.<key>}} | Значение композита. |
{{action}}, {{decision.slug}}, {{decision.version}}, {{execution.id}} | Запуск. |
{{delivery.id}} | ID этой доставки dlv_… — одинаковый при каждой попытке. |
{{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, объектом. - Внутри кавычек она становится текстом внутри этой строки, экранированным по необходимости.
Для решения, у объектного state которого есть поля email и company_size, с параметром email, взятым из state.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}}— поле объектного state,{{result.route}}— вопрос с именемroute; - имена секретов пишутся в UPPER_SNAKE_CASE, например
{{secrets.CRM_TOKEN}}; - каждой
{{нужна своя}}, с одной переменной внутри; - секреты нельзя использовать в текстах.
Отсутствующий секрет не является ошибкой схемы — секреты меняются без публикации, — но доставка, которая на него ссылается, завершается ошибкой, пока он не задан. См. Секреты рабочего пространства.
Триггеры назначений
Когда срабатывает назначение — условия на ответы, уверенность, взвешенные уровни и composites, итоговые действия, минимальная уверенность на маршрут, уровни score, пороги вероятности — и в каком порядке.
Готовые ответы
Возвращайте готовое сообщение — текст и необязательные кнопки, с переменными — в ответе API для заданного результата, мгновенно и без вызова какой-либо модели.