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

# Background Tasks

> Execute long-running operations asynchronously

Background tasks let runnables execute asynchronously while the agent continues. When a tool runs in the background, it immediately returns a `task_id` and `status: "running"` instead of blocking until completion.

## Configuring Background Mode

The `background_mode` parameter controls when a runnable executes asynchronously:

* `"never"` (default) — always runs synchronously
* `"always"` — always runs in the background
* `"auto"` — the LLM decides per call by setting `run_in_background=True` on the tool input

```python theme={"dark"}
from timbal import Tool

long_running_tool = Tool(
    handler=slow_operation,
    background_mode="always",
)
```

The built-in `Bash` tool uses `background_mode="auto"` by default. The model can run a shell command in the background by passing `run_in_background=True`.

```python theme={"dark"}
from timbal import Agent
from timbal.tools import Bash

agent = Agent(
    name="task_manager",
    model="openai/gpt-4o-mini",
    tools=[Bash("*")],
)

# Agent starts the command in the background and returns immediately
result = await agent(prompt="Install project dependencies in the background").collect()
```

## Checking Task Status

Background tools return immediately with a task handle:

```python theme={"dark"}
{"task_id": "a3k9f2", "status": "running"}
```

Once at least one background task is running, the agent automatically exposes a `get_background_task` tool. Call it with the `task_id` to poll status and drain queued events:

```python theme={"dark"}
from timbal.state import get_run_context

# After starting a background task...
span = get_run_context().current_span()
status = span.runnable.get_background_task("a3k9f2")
# {"status": "running" | "completed" | "error" | "cancelled" | "not_found", "events": [...], ...}
```

Or let the agent poll for you on a follow-up turn — it will see `get_background_task` in its tool list and can call it with the `task_id` from the earlier tool result.