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

All runnables must have a unique name. This name is used for tracing, debugging, and referencing the runnable in workflows, agents, and other components. Whether you’re creating a Tool, an Agent, or a Workflow, the name parameter is required and must be unique within your application context. 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() # Returns 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() # Returns 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() # Returns a number between 5 - 15

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

result = await add_tool(a=5, b=10).collect() # Returns 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

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