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

# Building Agents

> Start simple: a model, tools, and instructions.

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

```python weather_agent.py theme={null}
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

<Steps>
  <Step title="Set up your environment">
    <Snippet file="setup-venv.mdx" />
  </Step>

  <Step title="Install Definable">
    <Snippet file="install-definable.mdx" />
  </Step>

  <Step title="Export your API key">
    <Snippet file="export-openai-key.mdx" />
  </Step>

  <Step title="Run">
    ```bash theme={null}
    python weather_agent.py
    ```
  </Step>
</Steps>

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

```python theme={null}
# 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)
```

<Snippet file="models-note.mdx" />

## Next Steps

| Task                                       | Guide                                    |
| ------------------------------------------ | ---------------------------------------- |
| Configure retries, limits, and compression | [Configuration](/agents/configuration)   |
| Run agents sync, async, and streaming      | [Running agents](/agents/running-agents) |
| Add reasoning before responses             | [Thinking](/reasoning/thinking)          |
| Add persistent memory                      | [Memory](/memory/overview)               |
| Ground agents in documents                 | [Knowledge](/knowledge/overview)         |
| Define custom tools                        | [Tools](/tools/overview)                 |
| Deploy to messaging platforms              | [Interfaces](/interfaces/overview)       |
| Coordinate multiple agents                 | [Teams](/teams/overview)                 |