Features

Installation

# Core framework
pip install stirrup # or: uv add stirrup
# With all optional components
pip install 'stirrup[all]' # or: uv add 'stirrup[all]'
# Individual extras
pip install 'stirrup[litellm]' # or: uv add 'stirrup[litellm]'
pip install 'stirrup[docker]' # or: uv add 'stirrup[docker]'
pip install 'stirrup[e2b]' # or: uv add 'stirrup[e2b]'
pip install 'stirrup[mcp]' # or: uv add 'stirrup[mcp]'

Quick Start

import asyncio
from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
async def main() -> None:
 """Run an agent that searches the web and creates a chart."""
 # Create client using ChatCompletionsClient
 # Automatically uses OPENROUTER_API_KEY environment variable
 client = ChatCompletionsClient(
 base_url="https://openrouter.ai/api/v1",
 model="anthropic/claude-sonnet-4.5",
 )
 # As no tools are provided, the agent will use the default tools, which consist of:
 # - Web tools (web search and web fetching, note web search requires BRAVE_API_KEY)
 # - Local code execution tool (to execute shell commands)
 agent = Agent(client=client, name="agent", max_turns=15)
 # Run with session context - handles tool lifecycle, logging and file outputs
 async with agent.session(output_dir="./output/getting_started_example") as session:
 finish_params, history, metadata = await session.run(
 """
 What is the population of Australia over the last 3 years? Search the web to find out and create a
 simple chart using matplotlib showing the current population per year."""
 )
 print("Finish params: ", finish_params)
 print("History: ", history)
 print("Metadata: ", metadata)
if __name__ == "__main__":
 asyncio.run(main())

Full Customization

# Clone the repository
git clone https://github.com/ArtificialAnalysis/Stirrup.git
cd stirrup
# Install in editable mode
pip install -e . # or: uv venv && uv pip install -e .
# Or with all optional dependencies
pip install -e '.[all]' # or: uv venv && uv pip install -e '.[all]'

How It Works

Using Other LLM Providers

OpenAI-Compatible APIs

# Create client using Deepseek's OpenAI-compatible endpoint
client = ChatCompletionsClient(
 base_url="https://api.deepseek.com",
 model="deepseek-chat", # or "deepseek-reasoner" for R1
 api_key=os.environ["DEEPSEEK_API_KEY"],
)
agent = Agent(client=client, name="deepseek_agent")

LiteLLM (Anthropic, Google, etc.)

# Ensure LiteLLM is added with: pip install 'stirrup[litellm]' # or: uv add 'stirrup[litellm]'
# Create LiteLLM client for Anthropic Claude
# See https://docs.litellm.ai/docs/providers for all supported providers
client = LiteLLMClient(
 model_slug="anthropic/claude-sonnet-4-5",
 max_tokens=200_000,
)
# Pass client to Agent - model info comes from client.model_slug
agent = Agent(
 client=client,
 name="claude_agent",
)

Default Tools

Extending with Pre-Built Tools

import asyncio
from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import CALCULATOR_TOOL, DEFAULT_TOOLS
# Create client for OpenRouter
client = ChatCompletionsClient(
 base_url="https://openrouter.ai/api/v1",
 model="anthropic/claude-sonnet-4.5",
)
# Create agent with default tools + calculator tool
agent = Agent(
 client=client,
 name="web_calculator_agent",
 tools=[*DEFAULT_TOOLS, CALCULATOR_TOOL],
)

Defining Custom Tools

from pydantic import BaseModel, Field
from stirrup import Agent, Tool, ToolResult, ToolUseCountMetadata
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import DEFAULT_TOOLS
class GreetParams(BaseModel):
 """Parameters for the greet tool."""
 name: str = Field(description="Name of the person to greet")
 formal: bool = Field(default=False, description="Use formal greeting")
def greet(params: GreetParams) -> ToolResult[ToolUseCountMetadata]:
 greeting = f"Good day, {params.name}." if params.formal else f"Hey {params.name}!"
 return ToolResult(
 content=greeting,
 metadata=ToolUseCountMetadata(),
 )
GREET_TOOL = Tool(
 name="greet",
 description="Greet someone by name",
 parameters=GreetParams,
 executor=greet,
)
# Create client for OpenRouter
client = ChatCompletionsClient(
 base_url="https://openrouter.ai/api/v1",
 model="anthropic/claude-sonnet-4.5",
)
# Add custom tool to default tools
agent = Agent(
 client=client,
 name="greeting_agent",
 tools=[*DEFAULT_TOOLS, GREET_TOOL],
)

Next Steps

Documentation

uv run mkdocs serve

Development

# Format and lint code
uv run ruff format
uv run ruff check
# Type check
uv run ty check
# Run tests
uv run pytest tests

License