Skip to main content

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.

​
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.

​
Model Providers

You can specify any model using the “provider/model” format. See all supported models in Model Capabilities. Some models support advanced capabilities like thinking/reasoning, which enables extended reasoning processes for complex problem-solving. 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-latest",
    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. 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 approval_decisions: 
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",
    approval_decisions={approval_id: True},
).collect()
The full reference — durable cross-process resume, audit fields, redaction, parallel gates, pending_approvals(), status reasons, usage counters — lives on the dedicated Human-in-the-Loop Approvals page.

​
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: 
# 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: 
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-latest"
response = await agent(
    prompt="What is the capital of Germany?",
    model="anthropic/claude-sonnet-4-latest"
).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 (provider-specific format)
# 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-latest",
    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/reasoning 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
  • ToolCallContent - 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

# Message with text and file
mixed_message = Message(
    role="user",
    content=[
        TextContent(text="Analyze this document:"),
        FileContent(path=File.validate("report.pdf"))
    ]
)
The same message above can be created easily using Message.validate(): 
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")