Skip to main content

​
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 require specific parameters (like max_tokens for Claude). Use model_params to pass any additional model configuration: 
agent = Agent(
    name="claude_agent",
    model="anthropic/claude-sonnet-4-latest",
    model_params={
        "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
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=Message.validate("What is the capital of Germany?")
).collect()
For real-time processing, you can stream events as they happen: 
async for event in agent(prompt="Hello"):
    print(event)

​
Input and Output

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()
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.')])

# Access the message text
print(result.output.content[0].text)
# "2 + 2 = 4."

​
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")