Overview

What are Agents?

Agents are autonomous execution units that orchestrate LLM interactions with tool calling. Without tools, an agent functions as a basic LLM. The simplest agent requires just a name and model:

from timbal import Agent

agent = Agent(
    name="my_agent",
    model="openai/gpt-5"
)  # That's it! You've created your first agent!

For a full step-by-step guide, check the quickstart section or see practical examples in the examples section.

Reading guide

The sidebar follows a basics → platform → production path. You can jump anywhere, but this order matches how most agents are built:

Tools — give the agent capabilities (the core primitive)
Structured output — constrain what comes back
Memory → Memory compaction — multi-turn context, then keeping it within the window
Skills — domain packages (knowledge + tools) once the agent loop makes sense
Dynamic agents — runtime prompts and tool sets
Background tasks · Commands — utilities (async tools, slash shortcuts)

After Workflows, see Human in the loop for approvals, suspend(), and durable resume (agents, workflow steps, and tools). This page covers running agents, models, and I/O. The sections below are the reference for that; the linked pages go deeper on each topic.

Model Providers

You can specify any model using the “provider/model” format. See all supported models in the Model Reference. Some models require specific parameters (like max_tokens for Claude). Pass it as a top-level field:

agent = Agent(
    name="claude_agent",
    model="anthropic/claude-sonnet-4-6",
    max_tokens=1024
)

Note: Make sure to define all required environment variables—such as the API key model that you need—in your .env file.

OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_claude_api_key

Fallback Models

Use FallbackModel when you want an agent to try another model if the primary provider is rate limited, temporarily unavailable, times out, or returns a retryable server error.

from timbal import Agent, FallbackModel

agent = Agent(
    name="support_agent",
    model=FallbackModel(
        "anthropic/claude-sonnet-4-6",
        "openai/gpt-5.5",
        "google/gemini-2.5-pro",
    ),
    max_tokens=1024,  # Required for Anthropic models
)

Models are tried in order. By default, each model gets two retries before Timbal moves to the next model in the chain. If every model fails with a retryable provider error, Timbal raises FallbackExhausted with the per-model errors. For per-model settings, use ModelEntry:

from timbal import Agent, FallbackModel, ModelEntry

agent = Agent(
    name="support_agent",
    model=FallbackModel(
        ModelEntry(
            "anthropic/claude-sonnet-4-6",
            max_retries=3,
            retry_delay=0.5,
        ),
        ModelEntry(
            "openai/gpt-5.5",
            max_retries=1,
        ),
    ),
    max_tokens=1024,
)

Fallback only switches models before the first streamed chunk is emitted. If a stream fails after output has started, Timbal raises the error instead of silently switching models and risking duplicated or inconsistent output.

Thinking and reasoning

Some models support extended thinking before responding. Check per-model capabilities on the Model Reference pages. Configure at construction time via model_params (per-request overrides use provider_params — see Overriding Model Configuration below):

# Anthropic — max_tokens required; budget_tokens must be < max_tokens
agent = Agent(
    name="reasoning_agent",
    model="anthropic/claude-sonnet-4-6",
    max_tokens=20000,
    model_params={"thinking": {"type": "enabled", "budget_tokens": 10000}},
)

# OpenAI
agent = Agent(
    name="reasoning_agent",
    model="openai/gpt-5",
    model_params={"reasoning": {"effort": "high", "summary": "auto"}},
)

Define tools as Python functions - the framework handles schema generation, parameter validation, and execution orchestration.

Running Agents

Execute agents by calling them with a prompt parameter and using .collect() to get the result:

response = await agent(
    prompt="What is the capital of Germany?"
).collect()

Streaming Events

For real-time processing, you can stream events as they happen:

async for event in agent(prompt="Hello"):
    print(event)

Approval-Required Tools

Any runnable — Tool, Agent, or Workflow step — can pause for human approval before it runs. Mark it with requires_approval, listen for ApprovalEvent, and resume by calling the runnable again with resume:

from timbal import Agent, Tool
from timbal.types.events import ApprovalEvent


refund = Tool(
    handler=lambda amount: f"refunded ${amount}",
    requires_approval=lambda amount: amount > 100,
    approval_prompt=lambda amount: f"Approve refunding ${amount}?",
)

agent = Agent(name="support_agent", model="openai/gpt-5", tools=[refund])

approval_id = None
async for event in agent(prompt="Refund $250"):
    if isinstance(event, ApprovalEvent):
        approval_id = event.approval_id

result = await agent(
    prompt="Refund $250",
    resume={approval_id: True},
).collect()

The full reference — durable cross-process resume, audit fields, redaction, parallel gates, pending_approvals(), status reasons, usage counters, plus suspend() for asking the user mid-run — lives on the dedicated Human in the Loop section.

Input

Agents communicate through Message objects - Timbal’s data structure that standardizes both input and output.

from timbal.types.message import Message

response = await agent(
    prompt=Message.validate("What is the capital of Germany?")
).collect()

Agents accept multiple input formats, automatically converting them to Message objects:

from timbal.types.file import File

# String
response = await agent(
    prompt="What's the weather?"
).collect()

# File - Timbal type
response = await agent(
    prompt=File.validate("image.png")
).collect()

# List
response = await agent(
    prompt=["Describe this image", File.validate("image.png")]
).collect()

### Passing Input Parameters

You can pass custom input parameters when calling an agent. Access these values anywhere in your agent (tools, system prompts, hooks) using `get_run_context().current_span().input`:

```python
from timbal import Agent, Tool
from timbal.state import get_run_context

def get_user_info():
    span = get_run_context().current_span()
    user_id = span.input.get("user_id")
    role = span.input.get("role")
    return f"User {user_id} with role {role}"

agent = Agent(
    name="user_agent",
    model="openai/gpt-4o-mini",
    tools=[Tool(handler=get_user_info)]
)

# Pass custom inputs
response = await agent(
    prompt="Who am I?",
    user_id="123",
    role="admin"
).collect()

The tool can access user_id and role from the input parameters. Input parameters work with both .collect() and streaming.

For more information about accessing input parameters and using the run context, see the Context & State Management page.

Overriding Model Configuration

What if you want to change the model, max_tokens, or thinking config for each run? Instead of creating multiple agents, you can pass these as input parameters. This is useful for A/B testing different models, adjusting token limits per request, or dynamically selecting models based on task complexity.

# Agent with default values
agent = Agent(
    name="my_agent",
    model="openai/gpt-4o-mini",  # Default model
    max_tokens=1024  # Default max_tokens
)

# Override model: was "openai/gpt-4o-mini", now "anthropic/claude-sonnet-4-6"
response = await agent(
    prompt="What is the capital of Germany?",
    model="anthropic/claude-sonnet-4-6"
).collect()

# Override max_tokens: was 1024, now 2048
async for event in agent(
    prompt="What is the capital of Germany?",
    max_tokens=2048
):
    print(event)

# Override thinking via provider_params at call time (provider-specific format).
# At construction time, use model_params instead — same keys, same shape.
# For OpenAI: pass "reasoning" key
response = await agent(
    prompt="Solve this complex problem",
    model="openai/gpt-5.5",
    provider_params={"reasoning": {"effort": "high", "summary": "auto"}}
).collect()

# For Anthropic: pass "thinking" key
response = await agent(
    prompt="Solve this complex problem",
    model="anthropic/claude-sonnet-4-6",
    provider_params={"thinking": {"type": "enabled", "budget_tokens": 10000}}
).collect()

The parameter names model, max_tokens, and provider_params are reserved and will affect model configuration when passed as input. These parameters will not be available as regular input to your agent. If you need to pass custom data without changing the actual model configuration, use different parameter names (e.g., data_model instead of model if you want to pass a data model name).

Output

Calling .collect() returns an OutputEvent containing the agent’s response. Access the Message via the .output property:

Learn more about events in Events & Streaming.

result = await agent(prompt="What's 2+2?").collect()

# result is an OutputEvent
print(result.output)
# Message(role=assistant, content=[TextContent(type='text', text='2 + 2 = 4.')])

# You can access content directly
print(result.output.content[0].text)
# "2 + 2 = 4."

# However, the best way to get text is using collect_text()
print(result.output.collect_text())
# "2 + 2 = 4."

Important: When using models with thinking enabled, the content array structure changes:

content[0] will contain the thinking/reasoning content
content[1] will contain the actual text response

Directly accessing result.output.content[0].text may return thinking content instead of the response text. Always use collect_text() to reliably extract the text response, regardless of whether thinking is enabled.

Messages

Messages are the structured data format that agents use to communicate. They contain a role and content, with automatic handling of different content types and provider compatibility.

from timbal.types.message import Message

Messages contain a role and content: Role Types:

user - Messages from the user
assistant - Messages from the AI agent
system - System instructions and context
tool - Tool execution results

Content Types:

TextContent - Plain text messages
FileContent - Files like PDFs, images, documents
ToolUseContent - Function calls to tools
ToolResultContent - Results from tool executions

Messages can contain different types of content - text, files, tool calls, and tool results. The framework automatically handles complex content structures:

from timbal.types.content import FileContent, TextContent
from timbal.types.file import File

# Message with text and file
mixed_message = Message(
    role="user",
    content=[
        TextContent(text="Analyze this document:"),
        FileContent(file=File.validate("report.pdf"))
    ]
)

The same message above can be created easily using Message.validate():

from timbal.types.file import File

message = Message.validate([
    "Summarize this document:",
    File.validate("quarterly_report.pdf")
])

Files

Agents can process files directly through the message content system. The framework automatically handles file reading, content extraction, and formatting for the AI model.

from timbal.types.file import File

The framework supports common document and media formats:

Text files (.txt, .md) - Direct content inclusion
PDFs (.pdf) - Text extraction with structure preservation
Images (.png, .jpg, .gif) - Visual analysis through vision-capable models
Spreadsheets (.xlsx, .csv) - Structured data representation
Documents (.docx) - Text and formatting extraction

Files are automatically converted to Timbal File objects using File.validate():

file = File.validate("quarterly_report.pdf")

Getting started

Core Concepts

Agents

Workflows

Human in the Loop

Evals

Deployment

What are Agents?

Reading guide

Model Providers

Fallback Models

Thinking and reasoning

Running Agents

Streaming Events

Approval-Required Tools

Input

Overriding Model Configuration

Output

Messages

Files

​What are Agents?

​Reading guide

​Model Providers

​Fallback Models

​Thinking and reasoning

​Running Agents

​Streaming Events

​Approval-Required Tools

​Input

​Overriding Model Configuration

​Output

​Messages

​Files

What are Agents?

Reading guide

Model Providers

Fallback Models

Thinking and reasoning

Running Agents

Streaming Events

Approval-Required Tools

Input

Overriding Model Configuration

Output

Messages

Files