Building Agents

To build effective agents, start simple: a model, tools, and instructions. Once that works, layer in more functionality as needed.

weather_agent.py

from definable.agent import Agent
from definable.tool.decorator import tool

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny, 72F."

agent = Agent(
    model="gpt-4o",
    tools=[get_weather],
    instructions="You are a helpful weather assistant. Always check the weather before answering.",
)

output = agent.run("What's the weather in Tokyo?")
print(output.content)

Run Your Agent

Set up your environment

python3 -m venv .venv
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\activate

uv venv --python 3.12
source .venv/bin/activate

Install Definable

pip install definable

uv pip install definable

poetry add definable

Export your API key

export OPENAI_API_KEY=sk-***

setx OPENAI_API_KEY sk-***

Run

python weather_agent.py

How It Works

The agent sends your message and tool definitions to the model.
The model decides which tools to call (if any).
Tools execute and results are returned to the model.
The model produces a final text response.

This loop repeats until the model responds without tool calls or max_iterations is reached.

Development vs Production

Use agent.run() for production. It returns a typed RunOutput with content, messages, metrics, and status.

# Development — quick iteration
output = agent.run("What's the weather?")
print(output.content)

# Production — async with streaming
async for event in agent.arun_stream("What's the weather?"):
    if event.event == "RunContent":
        print(event.content, end="", flush=True)

You can use string shorthand instead of importing model classes:

# These are equivalent
agent = Agent(model=OpenAIChat(id="gpt-4o"))
agent = Agent(model="openai/gpt-4o")
agent = Agent(model="gpt-4o")  # defaults to OpenAI

Supported providers: openai, deepseek, moonshot, xai, anthropic, mistral, google, perplexity, ollama, openrouter.

Next Steps

Task	Guide
Configure retries, limits, and compression	Configuration
Run agents sync, async, and streaming	Running agents
Add reasoning before responses	Thinking
Add persistent memory	Memory
Ground agents in documents	Knowledge
Define custom tools	Tools
Deploy to messaging platforms	Interfaces
Coordinate multiple agents	Teams

Get Started

Basics

Capabilities

Advanced

Run Your Agent

How It Works

Development vs Production

Next Steps

​Run Your Agent

​How It Works

​Development vs Production

​Next Steps

Run Your Agent

How It Works

Development vs Production

Next Steps