Skip to main content
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
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. 
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: 
{"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: 
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.