> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Variables and Templates

> Declare Figranium task variables, override them at runtime, and use the SDK variable() helper to build the {$name} template tokens actions expect.

Figranium tasks accept typed variables and reference them inside action values with a `{$name}` template. The Python SDK ships a `variable()` helper that produces the correct token, plus typed shapes for declaring variables on a `Task`.

## Declare task variables

Task variables live under `task["variables"]`. Each entry has a `type` and a default `value`.

```python theme={null}
from figranium import Task

task: Task = {
    "name": "Search",
    "url": "https://example.com",
    "mode": "agent",
    "variables": {
        "query": {"type": "string", "value": "figranium"},
        "limit": {"type": "number", "value": 10},
        "strict": {"type": "boolean", "value": True},
    },
    "actions": [
        # ...
    ],
}
```

Variable `type` is `"string"`, `"number"`, or `"boolean"`. Additional fields are allowed on each variable entry, and unknown fields are preserved by the SDK's flexible task type.

## Reference variables in actions

Anywhere an action expects a string value, use `variable(name)` to reference a task variable. The helper returns `{$name}`.

```python theme={null}
from figranium import actions, variable

actions.type("#search", variable("query"))
actions.set("activeQuery", variable("query"))
actions.request(
    "https://api.example.com/search",
    method="POST",
    body='{"q": "' + variable("query") + '"}',
)
```

`variable("")` raises `ValueError`; names must not be empty or whitespace-only.

## Override at runtime

Pass `variables` when executing a task to override the defaults for a single run. Runtime variables use plain values, not the typed shape used at declaration time.

```python theme={null}
result = client.run_task(task_id, {
    "variables": {
        "query": "browser automation",
        "limit": 25,
    },
})
```

You can also pass `taskVariables`, which sets task-scoped defaults for the run without changing the saved task.

```python theme={null}
client.run_task(task_id, {
    "variables": {"query": "figranium"},
    "taskVariables": {"userAgent": "custom"},
})
```

## Direct execution

`scrape`, `agent`, and `headful` accept the same runtime variable shape when called directly:

```python theme={null}
client.scrape({
    "url": "https://example.com",
    "variables": {"query": "figranium"},
})
```

See [Execution resource](/docs/sdk/python/resources/execution) for full input shapes.

## Auto-created variables

Some server-side flows auto-create variables (for example when a script writes a result to a new name). Those entries include `"autoCreated": True`. The SDK preserves the flag on read and write.

<Tip>
  Use `variable()` for every template reference so your code stays type-safe and refactorable. Hard-coding `{$name}` strings is brittle when variable names change.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Actions" icon="click" href="/docs/sdk/python/actions">
    Every action helper that accepts a template value.
  </Card>

  <Card title="Tasks resource" icon="list-check" href="/docs/sdk/python/resources/tasks">
    Full reference for saving and running tasks.
  </Card>
</CardGroup>