Skip to main content
This guide walks you through creating your first agent with tools. By the end, you’ll have a working agent that can perform calculations.

​
Prerequisites

  • Python 3.11+ or Node.js 20+
  • An Opper API key (get one here)

​
1. Install the SDK

pip install opper-agents

​
2. Set Your API Key

export OPPER_API_KEY="your-api-key"

​
3. Create Your First Agent

Create a file and add the following code: 
# math_agent.py
import asyncio
from opper_agents import Agent, tool

@tool
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

@tool
def multiply(a: int, b: int) -> int:
    """Multiply two numbers together."""
    return a * b

agent = Agent(
    name="MathAgent",
    description="A helpful math assistant",
    tools=[add, multiply],
    verbose=True  # See what the agent is thinking
)

async def main():
    result = await agent.process("What is 5 + 3, then multiply by 2?")
    print(f"Result: {result}")

asyncio.run(main())

​
4. Run Your Agent

python math_agent.py
You’ll see output like: 
[MathAgent] Thinking...
[MathAgent] Calling tool: add(a=5, b=3)
[MathAgent] Tool result: 8
[MathAgent] Calling tool: multiply(a=8, b=2)
[MathAgent] Tool result: 16
[MathAgent] Done!
Result: 16

​
What Just Happened?

  1. The agent received your question
  2. It analyzed the available tools (add, multiply)
  3. It decided to first call add(5, 3) to get 8
  4. Then it called multiply(8, 2) to get 16
  5. Finally, it returned the result
The agent figured out the multi-step plan on its own!

​
5. Add Structured Output

For production use, you’ll want typed outputs. Add an output schema: 
from pydantic import BaseModel, Field

class MathResult(BaseModel):
    answer: float = Field(description="The final numerical answer")
    steps: list[str] = Field(description="Steps taken to solve")

agent = Agent(
    name="MathAgent",
    description="A helpful math assistant",
    tools=[add, multiply],
    output_schema=MathResult
)

result = await agent.process("What is 5 + 3, then multiply by 2?")
print(result.answer)  # 16.0
print(result.steps)   # ["Added 5 + 3 = 8", "Multiplied 8 × 2 = 16"]

​
Next Steps

Core Concepts: Tools

Learn all the ways to define tools

Agent Composition

Use agents as tools in other agents

Memory

Enable persistent memory across calls

Examples

See complete working examples