Documentation Index
Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
Use this file to discover all available pages before exploring further.
To build effective agents, start simple: a model, tools, and instructions. Once that works, layer in more functionality as needed.
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
Export your API key
export OPENAI_API_KEY=sk-***
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
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 |
