The lightweight foundation for building agents

Stirrup is a lightweight framework, or starting point template, for building agents. It differs from other agent frameworks by:

• Working with the model, not against it: Stirrup gets out of the way and lets the model choose its own approach to completing tasks (similar to Claude Code). Many frameworks impose rigid workflows that can degrade results.
• Best practices and tools built-in: We analyzed the leading agents (Claude Code, Codex, and others) to understand and incorporate best practices relating to topics like context management and foundational tools (e.g., code execution).
• Fully customizable: Use Stirrup as a package or as a starting template to build your own fully customized agents.

Note: This is the Python implementation, StirrupJS is the Typescript implementation.

Features

• 🧪 Code execution: Run code locally, in Docker, or in an E2B sandbox
• 🔎 Online search / web browsing: Search and fetch web pages
• 🔌 MCP client support: Connect to MCP servers and use their tools/resources
• 📄 Document input and output: Import files into context and produce file outputs
• 🧩 Skills system: Extend agents with modular, domain-specific instruction packages
• 🛠️ Flexible tool execution: A generic Tool interface allows easy tool definition
• 👤 Human-in-the-loop: Includes a built-in user input tool that enables human feedback or clarification during agent execution
• 🧠 Context management: Automatically summarizes conversation history when approaching context limits
• 🔁 Flexible provider support: Pre-built support for OpenAI-compatible APIs, LiteLLM, or bring your own client
• 🖼️ Multimodal support: Process images, video, and audio with automatic format conversion

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]'
pip install 'stirrup[browser]'  # or: uv add 'stirrup[browser]'

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-opus-5",
        max_tokens=8_192,
        context_window_tokens=1_000_000,
    )

    # 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())

Note: This example uses OpenRouter. Set OPENROUTER_API_KEY in your environment before running. Web search requires a BRAVE_API_KEY. The agent will still work without it, but web search will be unavailable.

Full Customization

For using Stirrup as a foundation for your own fully customized agent, you can clone and import Stirrup locally:

# 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]'

See the Full Customization guide for more details.

How It Works

• Agent - Configures and runs the agent loop until a finish tool is called or max turns reached
• session() - Context manager that sets up tools, manages files, and handles cleanup
• Tool - Define tools with Pydantic parameters
• ToolProvider - Manage tools that require lifecycle (connections, temp directories, etc.)
• default_tools() - Standard tools included by default: code execution and web tools

Using Other LLM Providers

For non-OpenAI providers, change the base URL of the ChatCompletionsClient, use the LiteLLMClient (requires installation of optional stirrup[litellm] dependencies), or create your own client.

OpenAI-Compatible APIs

# Create client using Deepseek's OpenAI-compatible endpoint
client = ChatCompletionsClient(
    base_url="https://api.deepseek.com",
    model="deepseek-v4-flash",  # or "deepseek-v4-pro" for the larger model
    max_tokens=8_192,
    context_window_tokens=1_000_000,
    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-opus-5",
    max_tokens=8_192,
    context_window_tokens=1_000_000,
)

# Pass client to Agent - model info comes from client.model_slug
agent = Agent(
    client=client,
    name="claude_agent",
)

See LiteLLM Example or Deepseek Example for complete examples.

Default Tools

When you create an Agent without specifying tools, it uses default_tools():

Each call returns fresh provider instances. Provider instances hold per-session state (a temp directory, an HTTP client), so concurrent sessions must not share them.

Breaking change: the DEFAULT_TOOLS list was removed because every caller shared the same two provider instances. Migrate tools=DEFAULT_TOOLS to tools=default_tools(), and tools=[*DEFAULT_TOOLS, extra_tool] to tools=[*default_tools(), extra_tool].

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-opus-5",
    max_tokens=8_192,
    context_window_tokens=1_000_000,
)

# 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-opus-5",
    max_tokens=8_192,
    context_window_tokens=1_000_000,
)

# Add custom tool to default tools
agent = Agent(
    client=client,
    name="greeting_agent",
    tools=[*default_tools(), GREET_TOOL],
)

Next Steps

• Getting Started - Installation and first agent tutorial
• Core Concepts - Understand Agent, Tools, and Sessions
• Examples - Working examples for common patterns
• Creating Tools - Build your own tools

Documentation

Full documentation: artificialanalysis.github.io/Stirrup

Build and serve locally:

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

Licensed under the MIT LICENSE.