> ## 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 in Kotlin

> 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 Kotlin 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 is a `TaskVariable` with a `type` and a default `value`.

```kotlin theme={null}
import dev.figranium.sdk.Task
import dev.figranium.sdk.TaskVariable
import kotlinx.serialization.json.JsonPrimitive

val task = Task(
    name = "Search",
    url = "https://example.com",
    mode = "agent",
    variables = mapOf(
        "query" to TaskVariable(type = "string", value = JsonPrimitive("figranium")),
        "limit" to TaskVariable(type = "number", value = JsonPrimitive(10)),
        "strict" to TaskVariable(type = "boolean", value = JsonPrimitive(true)),
    )
)
```

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}`.

```kotlin theme={null}
import dev.figranium.sdk.Actions
import dev.figranium.sdk.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 an `IllegalArgumentException`; 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 `JsonElement` values, not the typed `TaskVariable` shape used at declaration time.

```kotlin theme={null}
import kotlinx.serialization.json.JsonPrimitive

val result = client.runTask(
    id = "tsk_abc123",
    input = ExecuteTaskOptions(
        variables = mapOf(
            "query" to JsonPrimitive("browser automation"),
            "limit" to JsonPrimitive(25),
        )
    )
)
```

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

```kotlin theme={null}
client.runTask(
    id = "tsk_abc123",
    input = ExecuteTaskOptions(
        variables = mapOf("query" to JsonPrimitive("figranium")),
        taskVariables = mapOf("userAgent" to JsonPrimitive("custom"))
    )
)
```

## Direct execution

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

```kotlin theme={null}
client.scrape(
    input = mapOf(
        "url" to JsonPrimitive("https://example.com"),
        "variables" to buildJsonObject {
            put("query", JsonPrimitive("figranium"))
        },
    )
)
```

See [Execution resource](/docs/sdk/kotlin/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/kotlin/actions">
    Every action helper that accepts a template value.
  </Card>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.