Template variables

For the curious. Your AI agent handles template variables automatically. This explains how data flows between nodes and what’s happening when you see ${variable} syntax in workflows or traces.

Template variables let nodes pass data to each other without writing glue code. When you see ${variable} syntax in a workflow, it’s pulling data from previous nodes, workflow inputs, or nested structures.

Basic syntax

The ${variable} syntax accesses values from the shared store:

### summarize

Summarize the content from the read node.

- type: llm
- prompt: ${read.content}

Here, ${read.content} pulls the content output from the read node.

Nested access

Template variables can traverse deeply nested structures:

### extract

Extract the name of the first item from the API response.

- type: llm
- prompt: ${api.response.items[0].name}

This traverses:

api node’s output
response key
items array
First element ([0])
name field

Type preservation

Template variables preserve the original data type when used alone. When combined with text, they become strings.

Template	Original value	Result	Type
`"${count}"`	`42` (int)	`42`	int
`"Count: ${count}"`	`42` (int)	`"Count: 42"`	string
`"${config}"`	`{"key": "val"}`	`{"key": "val"}`	dict
`"Prefix ${config}"`	`{"key": "val"}`	`"Prefix {\"key\": \"val\"}"`	string

Simple templates (just ${var}) preserve type. Complex templates (any surrounding text) become strings.

Inline objects

This type preservation makes inline object construction intuitive:

### process

Process settings and results together.

- type: shell
```yaml stdin
config: ${settings}
data: ${results}
```

If settings is {"timeout": 30} and results is {"status": "ok"}, the resolved stdin is:

{
  "config": {"timeout": 30},
  "data": {"status": "ok"}
}

Without type preservation, both would be stringified JSON requiring manual parsing.

JSON auto-parsing

When a template accesses nested fields on a JSON string, pflow automatically parses it:

## Steps

### fetch

Fetch data from the API.

- type: shell

```shell command
curl https://api.example.com/data
```

### extract

Analyze the first result name from the fetched data.

- type: llm
- prompt: Analyze: ${fetch.stdout.results[0].name}

Even though fetch.stdout is a string containing JSON, the nested access ${fetch.stdout.results[0].name} works because pflow:

Sees you’re trying to access .results
Attempts to parse stdout as JSON
Traverses the parsed structure
Returns the value at results[0].name

This means shell commands that output JSON work directly with template variables — no manual json.loads() needed.

Workflow inputs

Template variables also reference workflow inputs declared in the workflow definition:

## Inputs

### api_key

API key for authenticating with the service.

- type: string

### endpoint

URL of the API endpoint to call.

- type: string

## Steps

### call_api

Call the API endpoint with authentication.

- type: http
- url: ${endpoint}
```yaml headers
Authorization: Bearer ${api_key}
```

When running this workflow, inputs are provided via CLI arguments:

pflow my-workflow api_key="sk-..." endpoint="https://api.example.com"

Stdin input

Inputs can receive piped data by adding stdin: true. See Stdin input for details.

Array notation

Array elements are accessed using bracket notation:

### extract

Extract specific items from the results.

- type: llm
- prompt: First: ${results[0]}, Tag: ${data.items[2].tags[1]}

Batch processing

In batch nodes, a special template variable (${item} by default) represents the current item:

### process

Summarize each file.

- type: llm
- prompt: Summarize: ${file}
- batch:
    items: ${files}
    as: file

The as: "file" creates ${file} as the item variable. See Batch processing for details.

Coalesce operator

The ?? operator returns the first operand that resolves, falling through whenever the left side isn’t there — whether the node didn’t run (a branch that wasn’t taken) or the referenced field is absent on a node that did run:

### report

Report the result from whichever branch ran.

- type: llm
- prompt: Result was: ${success_branch.stdout ?? fallback_branch.stdout}

This is particularly useful with conditional branching where only one path executes. Without coalesce, referencing a node that didn’t run would be an unresolved variable error. Operands can also be JSON literals, used as a final default when nothing else resolves:

- prompt: Retries so far: ${state.count ?? 0}
- prompt: Label: ${item.label ?? "untitled"}

Literal operands accept numbers, double-quoted strings, true, false, null, and empty []/{} (a literal string cannot contain the ?? sequence itself). A bare reference with no ?? fallback — ${node.field} — still raises an unresolved-variable error when the field is missing, so genuine typos are caught; add a fallback only where absence is expected.

Node metadata

Beyond their primary outputs, some nodes expose metadata that downstream nodes can access through templates. This is useful for cost-aware workflows, debugging, or building on execution details.

LLM token usage

Both llm and agent nodes write llm_usage with token counts:

### analyze

Analyze the document.

- type: llm
- model: openai/gpt-4o
- prompt: Analyze this document: ${doc.content}

### log_cost

Log the token usage from the analysis.

- type: shell

```shell command
echo "Model: ${analyze.llm_usage.model}, Tokens: ${analyze.llm_usage.total_tokens}"

Available fields on `${node_id.llm_usage}`:

| Field | Type | Description |
|-------|------|-------------|
| `model` | str | Model that was used |
| `input_tokens` | int | Total input tokens, including cached prefix tokens |
| `uncached_input_tokens` | int | Input tokens not covered by provider cache |
| `output_tokens` | int | Output tokens generated |
| `total_tokens` | int | Input + output |
| `cache_creation_input_tokens` | int | Tokens used for cache creation |
| `cache_read_input_tokens` | int | Tokens read from cache |
| `input_token_accounting` | str | How `input_tokens` was derived. `llm` varies by provider; the Claude agent backend reports `split_cache_fields`, while Codex reports `total_includes_cache`. |

### Agent metadata

The `agent` node includes additional execution metadata in `llm_usage` beyond the standard token fields:

| Field | Type | Description |
|-------|------|-------------|
| `cost_usd` | null | Paid provider cost is unavailable for agent backends |
| `api_equivalent_cost_usd` | float/null | Comparison estimate: SDK-reported for Claude; LiteLLM-estimated for Codex when usage is present and `model` is explicit and priced |
| `duration_ms` | int | Total execution time |
| `session_id` | str | Session ID (use with `resume` parameter to continue conversations) |
| `num_turns` | int | Number of conversation turns |
| `reasoning_output_tokens` | int | Codex reasoning tokens (Codex backend only) |
| `retries` | array | Usage records for superseded structured-output correction calls, when any |

Access via `${node_id.llm_usage.field}`:

```markdown
### step_one

Start an analysis session.

- type: agent
- backend: codex
- prompt: Analyze the codebase structure

### step_two

Continue the same session with follow-up work.

- type: agent
- backend: codex
- prompt: Now refactor the issues you found
- resume: ${step_one.llm_usage.session_id}

Shell command

The shell node stores the resolved command that was actually executed, accessible as ${node_id.command}. Useful for logging or debugging when the command is built dynamically from templates.

HTTP response details

The http node exposes response_headers (dict) and response_time (seconds as float) alongside the response body. Useful for handling pagination links, rate limit headers, or performance monitoring.

Per-node cost is available internally as llm_usage.cost_usd (estimated from token pricing, null for unknown models). Access it via a code node’s inputs dict — it’s not exposed as a template variable because pricing coverage varies by model. Aggregate cost across all nodes appears in the CLI JSON output after the workflow finishes.

Escaping

Literal ${...} text (not a template variable) uses double dollar signs to escape:

### print_price

Print the literal price variable.

- type: shell

```shell command
echo 'Price: $${PRICE}'
```

This produces the literal string Price: ${PRICE} instead of trying to resolve a variable.

Validation

pflow validates template variables at workflow creation time:

Unknown variables → Error: “Unresolved variable: ${typo}”
Type mismatches → Warning: “Expected string, got dict”
Invalid syntax → Error: “Invalid template: ${foo.}”

This works because node types declare their outputs — pflow knows at creation time what fields exist and what types they have. With arbitrary code, you’d discover these mismatches at runtime.

Compile-time vs runtime validation

Most validation happens when the workflow is created (compile-time). Some validations happen during execution (runtime):

Compile-time: Variable existence, type compatibility, syntax
Runtime: JSON parsing success, nested access on dynamic values

If JSON auto-parsing fails at runtime, you’ll see an “Unresolved variable” error.

Nodes overview - How nodes use template variables
Batch processing - Item variables in batch nodes
Debugging - Troubleshooting template issues

​Basic syntax

​Nested access

​Type preservation

​Inline objects

​JSON auto-parsing

​Workflow inputs

​Stdin input

​Array notation

​Batch processing

​Coalesce operator

​Node metadata

​LLM token usage

​Shell command

​HTTP response details

​Escaping

​Validation

​Related

Basic syntax

Nested access

Type preservation

Inline objects

JSON auto-parsing

Workflow inputs

Stdin input

Array notation

Batch processing

Coalesce operator

Node metadata

LLM token usage

Shell command

HTTP response details

Escaping

Validation

Related