Skip to main content
An agent is the core building block of the SDK. It wraps an LLM with tools, schemas, and configuration to create an autonomous system that can accomplish tasks.

​
Creating an Agent

The simplest agent just needs a name: 
from opper_agents import Agent

agent = Agent(name="SimpleAgent")
result = await agent.process("Hello!")

​
Configuration Options

Agents accept many configuration options: 
from opper_agents import Agent
from pydantic import BaseModel

class OutputSchema(BaseModel):
    answer: str
    confidence: float

agent = Agent(
    # Identity
    name="MyAgent",
    description="What this agent does",
    instructions="Detailed system prompt...",

    # Tools
    tools=[tool1, tool2],

    # Schemas
    input_schema=InputSchema,    # Optional
    output_schema=OutputSchema,  # Optional

    # Behavior
    max_iterations=25,           # Max think-act cycles
    model="gcp/gemini-flash-latest",  # LLM to use

    # Features
    enable_memory=False,         # Persistent memory
    enable_streaming=False,      # Token streaming

    # Debugging
    verbose=False,               # Print execution
    logger=None,                 # Custom logger

    # Opper config
    opper_api_key=None,          # API key (or use env var)
    opper_base_url=None,         # Custom API endpoint
)

​
Running an Agent

Use the process method to run an agent: 
# Simple string input
result = await agent.process("What is 2 + 2?")

# With input schema
result = await agent.process({"question": "What is 2 + 2?"})

# With parent span for tracing
result = await agent.process("What is 2 + 2?", parent_span_id="span-123")

​
Model Selection

Specify which LLM the agent uses: 
# Single model
agent = Agent(
    name="MyAgent",
    model="gcp/gemini-flash-latest"
)

# Fallback chain (tries in order)
agent = Agent(
    name="MyAgent",
    model=["anthropic/claude-sonnet", "openai/gpt-4o", "gcp/gemini-flash-latest"]
)
The default model is gcp/gemini-flash-latest.

​
Instructions vs Description

  • description: Short summary for external use (shown when agent is used as a tool)
  • instructions: Full system prompt for the agent’s behavior
agent = Agent(
    name="ResearchAgent",
    description="Researches topics and provides summaries",  # For other agents
    instructions="""You are a thorough research assistant.

When given a topic:
1. Search for relevant information
2. Cross-reference multiple sources
3. Synthesize findings into a clear summary
4. Cite your sources

Always be objective and note any conflicting information."""
)

​
Iteration Limits

The max_iterations parameter prevents infinite loops: 
agent = Agent(
    name="MyAgent",
    max_iterations=10  # Stop after 10 think-act cycles
)
If the agent reaches the limit without completing, it returns the best result it has.

​
Verbose Mode

Enable verbose mode to see what the agent is doing: 
agent = Agent(
    name="MyAgent",
    verbose=True
)
This prints:
  • When the agent starts thinking
  • Which tools it calls and with what arguments
  • Tool results
  • When it completes

​
Agent Context

During execution, the agent maintains context that tracks:
  • Session ID: Unique identifier for this execution
  • Iteration: Current loop iteration
  • Execution history: All think/act cycles
  • Usage: Token counts and costs
  • Tool calls: Record of all tool invocations
Access context through hooks: 
from opper_agents import hook

@hook("agent_end")
async def on_end(context, agent):
    print(f"Total tokens: {context.usage.total_tokens}")
    print(f"Iterations: {context.iteration}")

​
Next Steps

Tools

Add capabilities to your agent

Schemas

Type-safe inputs and outputs