opper-agents 0.4.0

Opper-based agent workflows SDK

Opper Agent SDK

A Python SDK for building AI agents with Opper Task Completion API. Create intelligent agents that use tools-based reasoning loops with dynamic tool selection, event tracking, and MCP integration.

Table of Contents

1. Features
2. Getting Started
3. Installation
4. Quick Start
   • Set up your environment
   • Explore the Examples
   • Model Selection
5. Agent as a Tool
6. MCP (Model Context Protocol) Integration
7. Hooks
8. Visualizing Agent Flow
9. Monitoring and Tracing
10. License
11. Support

1. Features

• Reasoning with customizable model: Think → Act reasoning loop with dynamic tool selection
• Extendable tool support: Support for MCP or custom tools with output schemas and examples
• Parallel tool execution: Run independent tool calls concurrently for lower latency
• Event Hooks: Flexible hook system for accessing any internal Agent event
• Composable interface: Agent supports structured input and output schema for ease of integration
• Multi-agent support: Agents can be used as tools for other agents with usage propagation
• Usage & Cost tracking: run() returns result + detailed token usage and cost breakdown
• Type Safety internals: Pydantic model validation throughout execution
• Error Handling: Robust error handling with retry mechanisms
• Tracing & Monitoring: Full observability with Opper's tracing system

2. Getting Started

Building an agent takes three steps:

from opper_agents import Agent, tool

# 1. Define your tools
@tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is sunny"

# 2. Create the agent
agent = Agent(
    name="WeatherBot",
    description="Helps with weather queries",
    tools=[get_weather]
)

# 3. Run it
run_result = await agent.run("What's the weather in Paris?")
print(run_result.result)  # The answer
print(run_result.usage)   # Token usage and cost

3. Installation

Prerequisites

• Python >= 3.11

Install from PyPI

pip install opper-agents

Or using UV:

uv pip install opper-agents

Install from Source (For Development)

If you want to contribute or modify the SDK:

1. Clone the repository:

git clone https://github.com/opper-ai/opperai-agent-sdk.git
cd opperai-agent-sdk

2. Install in editable mode:

# Using pip
pip install -e .

# Or using UV (recommended)
uv pip install -e .

4. Quick Start

4.1. Set up your environment

export OPPER_API_KEY="your-opper-api-key"

Get your API key at platform.opper.ai.

4.2. Explore the Examples

Check out the examples/ directory for working examples:

• Getting Started (examples/01_getting_started/): Basic agent usage, memory, hooks, parallel execution, tool schemas
• MCP Integration (examples/02_mcp_examples/): Connect to MCP servers
• Applied Agents (examples/applied_agents/): Real-world examples like multi-agent systems
• Custom Agents (examples/custom_agents/): Build specialized agent types

Run any example:

python examples/01_getting_started/01_first_agent.py

4.3. Model Selection

You can specify AI models at the agent level to control which model is used for reasoning. The SDK supports all models available through the Opper API:

# Create agent with specific model
agent = Agent(
    name="ClaudeAgent",
    description="An agent that uses Claude for reasoning",
    tools=[my_tools],
    model="anthropic/claude-4-sonnet"  # Model for reasoning and tool selection
)

If no model is specified, Opper uses a default model optimized for agent reasoning.

5. Agent as a Tool

Agents can be used as tools by other agents for delegation and specialization:

# Create specialized agents
math_agent = Agent(name="MathAgent", description="Performs calculations")
research_agent = Agent(name="ResearchAgent", description="Explains concepts")

# Use them as tools in a coordinator agent
coordinator = Agent(
    name="Coordinator",
    tools=[math_agent.as_tool(), research_agent.as_tool()]
)

See examples/01_getting_started/02_agent_as_tool.py for a complete example.

6. MCP (Model Context Protocol) Integration

The SDK supports MCP servers as tool providers, allowing agents to connect to external services. Both stdio and HTTP-SSE transports are supported.

from opper_agents import mcp, MCPServerConfig

# Configure an MCP server
filesystem_server = MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="docker",
    args=["run", "-i", "--rm", "..."]
)

# Use MCP tools in your agent
agent = Agent(
    name="FileAgent",
    tools=[mcp(filesystem_server)],
)

See examples/02_mcp_examples/ for working examples with filesystem, SQLite, and Composio servers.

7. Hooks

Hooks let you run code at specific points in the agent's lifecycle for logging, monitoring, or custom behavior:

Available hooks: agent_start, agent_end, agent_error, loop_start, loop_end, llm_call, llm_response, think_end, tool_call, tool_result, memory_read, memory_write, memory_error

from opper_agents import hook
from opper_agents.base.context import AgentContext
from opper_agents.base.agent import BaseAgent

@hook("agent_start")
async def log_start(context: AgentContext, agent: BaseAgent, **kwargs):
    print(f"Agent {agent.name} starting with goal: {context.goal}")

agent = Agent(
    name="MyAgent",
    hooks=[log_start],
    tools=[...]
)

# Or use the EventEmitter-style API
agent.on("agent_end", my_handler)
agent.once("agent_error", my_error_handler)

See examples/01_getting_started/05_hooks.py for all available hooks with detailed examples.

8. Visualizing Agent Flow

Generate Mermaid diagrams of your agent's structure showing tools, sub-agents, schemas, and hooks. Perfect for documentation and understanding complex multi-agent systems.

agent.visualize_flow(output_path="agent_flow.md")

9. Monitoring and Tracing

The agent provides comprehensive observability for production deployments:

Agent Tracing

• Agent-level spans: Track entire reasoning sessions
• Thought cycles: Monitor think-act iterations
• Tool execution: Performance metrics for each tool call
• Model interactions: AI reasoning and decision making

View your traces in the Opper Dashboard

10. License

This project is licensed under the MIT License - see the LICENSE file for details.

11. Support

• Documentation: Opper Documentation
• Issues: GitHub Issues
• Community: Opper Discord

---

Built with Opper