Variable Extraction: Comparing Your Options

Overview

There are four distinct mechanisms for getting structured data out of a conversation or into a tool call, and it's easy to reach for the wrong one. This page compares them side by side rather than re-explaining any one in depth — see Structured Outputs, Squads & Handoffs, and Variables for the full mechanics of each.

Runs after a call ends: the full transcript is processed by an LLM against a JSON Schema you define, and attached to an assistant via artifactPlan.structuredOutputIds. Best for post-call analytics, CRM sync, or reporting where the data doesn't need to exist until the call is over.

Runs at the moment of a handoff between squad members: a dedicated LLM extraction pass reads the transcript so far and extracts values per a schema you define on the handoff destination. Once extracted, those variables are available to all subsequent assistants in the chain — not just the one immediately receiving the handoff — and a new value replaces any prior variable with the same name. Best for passing conversation data forward between squad members mid-call.

The top-level parameters array on apiRequest and function tools (distinct from function.parameters, which the LLM sees). Values are set at config time, support Liquid templates like {{ customer.number }}, and involve no LLM reasoning at all — they're resolved server-side and merged into the tool call after the LLM's own generated arguments, so a static parameter always overrides any LLM-generated key with the same name. Best for injecting values the model must not be able to fake, such as a caller ID or call ID used as a security boundary.

Extracts specific fields out of one tool's JSON response via a JSON path and stores them as named variables, available to be referenced by subsequent tool calls' static parameters. This enables deterministic tool chaining — the LLM still decides when a tool runs, but the data handed between tools is fully server-controlled, regardless of what the LLM would otherwise do with it.

As a general rule: reach for structured outputs when the data only needs to exist after the call ends. Reach for handoff variable extraction when the data needs to travel between squad members during the call. Reach for static parameters whenever a value must be trustworthy enough to gate something security-sensitive — never let the LLM originate that value. Reach for tool response aliases when one tool's output needs to feed directly into another tool's input, deterministically, regardless of what the model does in between.