Templating and data

Operations read values with {{root.key}} tokens and write values with publish_fields or set_variable. Six roots are readable inside a tool; two of them, tooldata and userdata, are also where operations write.

{
  "kind": "http",
  "config": {
    "method": "POST",
    "url": "https://{{vars.api_domain}}/v2/bookings",
    "headers": { "Authorization": "Bearer {{secrets.CLINIC_API_KEY}}" },
    "body": {
      "slot_id": "{{args.slot_id}}",
      "customer": "{{userdata.customer_id}}",
      "phone": "{{system_vars.human_phone_number}}",
      "requested_at": "{{system_vars.now}}"
    }
  },
  "publish_fields": [
    { "path": "booking.reference", "key": "booking_reference", "store": "userdata" }
  ]
}

The six roots

Token	Reads	Written by
`{{args.key}}`	The arguments the model sent on this call	The model, against the tool’s `json_schema`
`{{tooldata.key}}`	This run’s scratch space, empty when the tool starts and dropped when it returns	`publish_fields` and `set_variable` earlier in this tree
`{{userdata.key}}`	The session’s state, shared with other tools, the prompt and later turns	The starting request, any tool, the contact record. See userdata
`{{system_vars.key}}`	Platform values: the call’s numbers and direction, and the clock	The platform. Read-only. See variables
`{{vars.key}}`	The agent’s declared variables, with the starting request’s values merged over them	The agent and the starting request. Read-only. See variables
`{{secrets.NAME}}`	A workspace secret, or the session’s own	You, or the request that started the session. Never shown to the model

Tokens resolve in every string inside an operation’s config: URL, headers, query, body, say text, if operands, frontend_rpc payload, handoff summary, send_dtmf digits — except {{secrets.…}}, which only an http operation may use (a code operation reads input.secrets). A secret anywhere else is refused at save, because those operations speak, show, store or compare what they resolve. Tokens do not resolve in:

a code operation’s TypeScript, which reads the same roots as input.args, input.tooldata and so on;
an http operation’s method;
a transfer destination, which is always a literal number.

Nested values are read with dots, and a numeric segment indexes an array: {{args.address.city}}, {{tooldata.slots.0.id}}.

How a token resolves

Situation	Result
The string is exactly one token	The value keeps its type: `"{{args.quantity}}"` sends the number `3`, `"{{tooldata.slots}}"` sends the array
The token is inside other text	The value is stringified into the text
The key is missing (`args`, `tooldata`, `userdata`, `vars`, `system_vars`)	`null` as a whole value, empty string inside text
The secret is missing	The tool fails before any operation runs

An http header or query value that is exactly one token resolving to nothing is left out of the request. system_vars.now, .date and .time are rendered at the moment the operation runs, in the agent’s timezone. The phone keys (human_phone_number, agent_phone_number, direction) are filled on phone calls, WhatsApp calls and chats and media streams, and empty on web calls, API chats, Telegram and test runs, so do not make one the only source of a value the tool needs. channel says which one the session is.

Tokens that are refused

A token whose root is not one of the six is an error at save, not text: a bare {{name}}, {{customer.number}} pasted from another platform, or a typo like {{userdate.name}}. There is no escape syntax; literal {{…}} text can only appear inside a code operation.

You write	Result
A root that is not one of the six	Error at save
A root with no key, such as `{{userdata}}`	Error at save
`{{args.X}}` where `X` is not a top-level property of `json_schema`	Error at publish
`{{tooldata.X}}` that no earlier operation in the chain publishes	Error at publish
`{{secrets.X}}` in any operation but `http`	Error at save
`{{secrets.X}}` for a secret the workspace does not have	Warning at publish: every session must supply `X` in its `secrets`
`{{system_vars.X}}` outside its seven keys	Error at publish
`{{recording.…}}`	Error at publish. It only resolves in an agent’s greeting
`{{userdata.X}}` that this tool does not publish first	Warning at publish. Something else must put `X` in the session
`{{system_vars.now}}`, `.date` or `.time` on an agent with no `timezone`	Error at agent publish
A phone key of `system_vars` on a text or video agent	Warning at agent publish: always empty
`{{vars.X}}` the calling agent does not declare	Warning at agent publish

A key published before an if is readable in both branches; a key published inside a branch is readable only later in that branch.

`tooldata` or `userdata`

tooldata is plumbing between two operations of one run. userdata is what the conversation should still know afterwards: it is readable by other tools and by the agent’s prompt, persisted with the session and merged onto the contact. Default to tooldata; a booking reference the agent must repeat later belongs in userdata, the API envelope you dug it out of does not. Keys starting with _talqing are reserved; writing one to userdata is refused.

`publish_fields`

http, code and frontend_rpc results are not visible to later operations until you publish values out of them. Each entry is {path, key?, store}:

{
  "kind": "http",
  "config": { "method": "GET", "url": "https://api.example.com/orders/{{args.order_id}}" },
  "silent": true,
  "publish_fields": [
    { "path": "order.status", "store": "tooldata" },
    { "path": "order.tracking.url", "key": "tracking_url", "store": "userdata" },
    { "path": "order.items.0.name", "key": "first_item", "store": "tooldata" }
  ]
}

Field	Required	Meaning
`path`	yes	Dotted path into the result. A numeric segment indexes an array
`key`	no	The name to publish under, matching `^[A-Za-z_][A-Za-z0-9_]*$`. Defaults to the path’s last segment, so `order.status` publishes as `status`
`store`	yes	`tooldata` or `userdata`

A path missing from the result fails the operation with publish field path 'order.status' was not found in operation output, and on_error decides what happens next. A null on the path is not missing: it publishes null. A background_execution operation cannot publish.

`set_variable`

Writes one templated value, with no operation to produce it. All three config fields are required.

{
  "kind": "set_variable",
  "config": { "key": "callback_number", "value": "{{system_vars.human_phone_number}}", "store": "userdata" }
}

value may be any JSON value; a single-token string keeps the resolved type. set_variable returns nothing to the model.

The HTTP operation

Request fields, failure rules and network rules.

Variables

Declaring vars, the system_vars keys and timezone.

Testing and publishing

Seed userdata, vars and a timezone and run the draft.

Get started

Build

Guides

Templating and data

The six roots

How a token resolves

Tokens that are refused

`tooldata` or `userdata`

`publish_fields`

`set_variable`

Next

The HTTP operation

Variables

Testing and publishing

​The six roots

​How a token resolves

​Tokens that are refused

​tooldata or userdata

​publish_fields

​set_variable

​Next

The HTTP operation

Variables

Testing and publishing

The six roots

How a token resolves

Tokens that are refused

`tooldata` or `userdata`

`publish_fields`

`set_variable`

Next