Runnables

What is a Runnable?

A Runnable is an executable unit capable of processing inputs and producing outputs through an async generator interface. It works as a wrapper that turns any callable into a standardized, traceable, and composable execution unit. All runnables provide a unified interface and execution pattern, enabling seamless composition regardless of their underlying implementation:

Tools - Function wrappers with automatic schema generation and explicit parameter control
Agents - Autonomous execution units that orchestrate LLM interactions with tool calling
Workflows - Programmable execution pipelines that orchestrate step-by-step processing

Names identify runnables in tracing, workflows, and agent tools. Give Agents and Workflows an explicit name. A Tool can infer its name from the handler function; lambdas and callable objects need an explicit name. Names must be unique among sibling tools or workflow steps, and nested paths distinguish names in separate parents. Here’s how to create a basic Tool:

from timbal import Tool

def add(a: float, b: float) -> float:
    """Add two numbers together."""
    return a + b

add_tool = Tool(
    name="add_tool",
    handler=add,
)

Parameter Handling and Basic Execution

Runnables can be called as a regular python function. You can pass parameters as keyword arguments, and they’ll be automatically mapped to the appropriate parameters in the underlying functions:

result = await add_tool(a=5, b=3).collect()
print(result.output)  # 8

You can also set default parameter values when creating the runnable:

add_tool = Tool(
    name="add_tool",
    handler=add,
    default_params={"b": 3}
)

result = await add_tool(a=5).collect()
print(result.output)  # 8

Default parameters can also be callables that are evaluated at runtime:

import random

add_tool = Tool(
    name="add_tool",
    handler=add,
    default_params={"b": lambda: random.randint(0, 10)}
)

result = await add_tool(a=5).collect()
print(result.output)  # A number between 5 and 15

Note that runtime parameters always override default values, including callable defaults:

result = await add_tool(a=5, b=10).collect()
print(result.output)  # 15

In the above example, b=10 is passed at runtime and overrides the callable default that would generate a random number.

Getting started

Core Concepts

Agents

Voice Agents

Workflows

Human in the Loop

Evals

Deployment

What is a Runnable?

Parameter Handling and Basic Execution

​What is a Runnable?

​Parameter Handling and Basic Execution

What is a Runnable?

Parameter Handling and Basic Execution