Skip to main content
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

1

Set up your environment

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

Install Definable

pip install definable
3

Export your API key

export OPENAI_API_KEY=sk-***
4

Run

python weather_agent.py

​
How It Works

  1. The agent sends your message and tool definitions to the model.
  2. The model decides which tools to call (if any).
  3. Tools execute and results are returned to the model.
  4. 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

TaskGuide
Configure retries, limits, and compressionConfiguration
Run agents sync, async, and streamingRunning agents
Add reasoning before responsesThinking
Add persistent memoryMemory
Ground agents in documentsKnowledge
Define custom toolsTools
Deploy to messaging platformsInterfaces
Coordinate multiple agentsTeams