Introducing Opper Agent SDKs - Framework for reliable, headless agents
By Göran Sandahl -
Note, October 2026: the Opper Agent SDK has been discontinued and is no longer maintained, so the code below is kept for reference only. To build agents on Opper today, use the framework you already know, such as Mastra, LangChain or the Vercel AI SDK, on Opper's gateway. See apps and frameworks.
We're excited to announce the release of our new Opper Agent SDK (Python & TypeScript) – a powerful framework designed specifically for building intelligent, headless agents that can reason, act, and collaborate seamlessly.
They run on Opper's gateway, so every agent can use any model in the catalogue and is traced end to end.
Whether you're building research assistants, automation tools, or complex multi-agent systems, our SDKs provide the foundation you need to create production-ready AI agents.
Getting Started: Your First Agent in 3 Steps
Building an agent with our SDK is remarkably simple. Here's everything you need to get started:
from opperai 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",
instructions="Help with weather queries.",
tools=[get_weather],
model="cerebras/gpt-oss-120b",
)
# 3. Run it
result = await agent.run("What's the weather in Paris?")
print(result.output)
That's it! Just set your OPPER_API_KEY environment variable and you're ready to go.
Extend Agent with Tools
One of our key differentiators is seamless integration with the Model Context Protocol (MCP), allowing your agents to connect to external services and data sources with minimal effort.
Custom tools
You can create custom tools:
@tool
def analyze_data(data: str) -> dict:
"""Analyze data and return insights."""
# Your analysis logic here
return {"insights": ["trend_up", "anomaly_detected"]}
@tool
def send_alert(message: str, priority: str = "medium") -> str:
"""Send an alert notification."""
# Your alerting logic here
return f"Alert sent: {message}"
MCP tools
You can connect to MCP servers for tools:
import os
from opperai import Agent
from opperai.agent.mcp import mcp, MCPStdioConfig
# Configure filesystem access
filesystem_server = MCPStdioConfig(
name="filesystem",
command="docker",
args=["run", "-i", "--rm", "-v", f"{os.getcwd()}:/workspace",
"node:20", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
)
# Configure database access
sqlite_server = MCPStdioConfig(
name="sqlite",
command="uvx",
args=["mcp-server-sqlite", "--db-path", "./data.db"],
)
# Create agent with MCP tools
agent = Agent(
name="DataAgent",
model="cerebras/gpt-oss-120b",
instructions="Answer questions using the filesystem and the database.",
tools=[mcp(filesystem_server), mcp(sqlite_server)],
)
Choosing the Right Model
One of the key advantages of the Opper Agent SDK is model interoperability - you can easily switch between different language models to optimize for your specific use case. The SDK supports all major model providers through Opper's unified API.
Model Selection Strategy
Different models excel at different types of tasks. You can test agents with different models by passing the model parameter. You can also test models in the Opper platform UI.
# For complex reasoning and planning tasks
reasoning_agent = Agent(
name="ReasoningAgent",
instructions="Plan and solve complex multi-step problems.",
model="openai/gpt-5", # Best for complex multi-step reasoning
tools=[complex_analysis, strategic_planning],
)
# For fast, cost-effective tasks
quick_agent = Agent(
name="QuickAgent",
instructions="Classify and extract data quickly.",
model="cerebras/gpt-oss-120b", # Ultra-fast inference
tools=[simple_classification, data_extraction],
)
# For specialized coding tasks
code_agent = Agent(
name="CodeAgent",
instructions="Analyze and refactor code.",
model="anthropic/claude-sonnet-4-5", # Excellent for code generation
tools=[code_analysis, refactoring],
)
Extend Agent logic with Hooks
One of the most powerful features of our SDK is the comprehensive hook system that lets you intercept and process agent behavior at any point in the execution lifecycle.
Example: Print each tool call
Hooks are plain functions that receive a context dict. Here we print every tool call the agent decides to make:
from opperai import Agent, Hooks
def on_tool_start(ctx: dict) -> None:
"""Print each tool call the agent decides to make."""
print(f"{ctx['agent']} calls {ctx['name']} with {ctx['input']}")
agent = Agent(
name="MyAgent",
model="cerebras/gpt-oss-120b",
instructions="This is my Agent",
hooks=Hooks(on_tool_start=on_tool_start),
)
Example: Time your tools
Here we hook in after each tool call to log how long it took and whether it failed. Hooks observe the run, so if a tool returns too much, such as a full web page, trim it inside the tool before it returns.
def on_tool_end(ctx: dict) -> None:
"""Log how long each tool took and whether it failed."""
status = "failed" if ctx["error"] else "ok"
print(f"{ctx['name']} {status} in {ctx['duration_ms']:.0f} ms")
agent = Agent(
name="MyAgent",
model="cerebras/gpt-oss-120b",
instructions="This is my Agent",
hooks=Hooks(on_tool_end=on_tool_end),
)
Sub-Agents: Agents as tools
We can also use agents as tools within other agents. This allows for creating sophisticated multi-agent systems with clean delegation patterns.
Simple Agent Delegation
# Create specialized agents
math_agent = Agent(
name="MathAgent",
model="cerebras/gpt-oss-120b",
instructions="Perform mathematical calculations. Always show your work step by step.",
tools=[calculate, solve_equation],
)
research_agent = Agent(
name="ResearchAgent",
model="cerebras/gpt-oss-120b",
instructions="Research and explain concepts. Provide clear, detailed explanations.",
tools=[search_web, summarize_content],
)
# Use them as tools in a coordinator
coordinator = Agent(
name="Coordinator",
model="cerebras/gpt-oss-120b",
instructions="Delegate tasks to the specialized agents.",
tools=[
math_agent.as_tool(name="math_agent", description="Performs mathematical calculations"),
research_agent.as_tool(name="research_agent", description="Researches and explains concepts"),
],
)
# The coordinator can now delegate tasks
result = await coordinator.run(
"Calculate the compound interest for $1000 at 5% for 10 years, "
"then research the history of compound interest"
)
Built-in Tracing and Observability
Every agent execution is automatically traced through Opper's observability system. You get:
- Complete execution traces showing the full reasoning process
- Tool execution metrics with timing and success rates
- Token usage tracking for cost monitoring
- Span hierarchy showing agent delegation patterns
- Real-time monitoring through the Opper Dashboard
# Automatic tracing - no code needed!
agent = Agent(name="MyAgent", instructions="...", tools=[...], model="cerebras/gpt-oss-120b")
result = await agent.run("My task")
# View traces at https://platform.opper.ai
# See complete execution flow, tool calls, and performance metrics
Production-Ready Features
Our SDKs are built for production use with:
- Type Safety: Full Pydantic model validation throughout
- Error Handling: Robust error handling with graceful degradation
- Conversations:
Conversationkeeps multi-turn state across agent runs - Async-First: Built for high-performance async operations
- Extensible Architecture: Easy to build custom agent types
- Comprehensive Testing: 90%+ test coverage with extensive examples
Getting Started Today
Ready to build your first headless agent? Here's how to get started:
-
Install the SDK:
pip install opperai -
Get your API key at platform.opper.ai
-
Set your environment:
export OPPER_API_KEY="your-api-key" -
Run the examples:
git clone https://github.com/opper-ai/opper-sdks.git cd opper-sdks/python python examples/agents/00_first_agent.py