Stirrup
The lightweight framework for building agents
Last verified:
What is Stirrup?
Stirrup is a lightweight, open-source framework for building AI agents, developed by Artificial Analysis. It serves as both a ready-to-use package and a starting template that developers can clone and fully customize. Unlike rigid agent frameworks that impose strict workflows, Stirrup lets the model drive its own approach to completing tasks, similar to Claude Code, while providing essential structure and built-in best practices.
Key features include essential tools built-in (online search/web browsing, code execution via local/Docker/E2B sandbox, MCP client, document input/output), a modular skills system for domain-specific extensions, automatic context summarization when approaching limits, flexible LLM provider support (OpenAI-compatible APIs, LiteLLM, or custom clients), multimodal support for images/video/audio with automatic format conversion, and built-in logging for debugging. The framework implements a generic Tool interface for easy custom tool definition and supports hierarchical agent patterns through sub-agents.
Stirrup is designed for AI developers, engineers, and researchers building custom AI agents who want flexibility without sacrificing core functionality. It's particularly suited for teams building production agents, developers experimenting with agent architectures, and anyone who wants to incorporate best practices from leading agents like Claude Code, Codex, and others without reinventing the wheel.
The framework is completely open-source and free to use, installed via pip. Users only pay for the LLM API calls they make through their chosen provider (OpenRouter, OpenAI, Anthropic, DeepSeek, etc.). Optional dependencies like Docker support and E2B cloud sandbox require separate service accounts but the core framework itself has no cost.
Stirrup pricing
Pricing model: Freemium
Stirrup is completely free and open-source with no paid tiers. Install via 'pip install stirrup' for the core framework or 'pip install stirrup[all]' for all optional components. There are no subscription fees or usage-based charges from Stirrup itself. Users only pay for LLM API calls through their chosen provider (OpenRouter, OpenAI, Anthropic, DeepSeek, Together AI, etc.). Optional components have separate requirements: stirrup[docker] needs Docker daemon, stirrup[e2b] needs E2B_API_KEY for cloud sandboxes, stirrup[litellm] adds LiteLLM support, stirrup[mcp] adds Model Context Protocol support, and stirrup[browser] adds browser tool support. Web search specifically requires a BRAVE_API_KEY environment variable.
Stirrup pros
- Open-source and completely free to use
- Lets models drive their own workflow instead of imposing rigid patterns
- Incorporates best practices from Claude Code and other leading agents
- Essential tools built-in (search, code execution, MCP, document IO)
- Three code execution backends: local, Docker, and E2B cloud sandbox
- Automatic context summarization when approaching token limits
- Supports OpenAI-compatible APIs and LiteLLM out of the box
- Multimodal support for images, video, and audio with auto-conversion
- Modular skills system for domain-specific instruction packages
- Generic Tool interface makes custom tools easy to define
- Built-in logging with progress spinners and syntax-highlighted results
- Sub-agent support for hierarchical agent patterns
- Session context manager handles tool lifecycle and file cleanup automatically
- Can be used as a package or cloned as a customization template
- Flexible finish tools allow structured output customization
- Web search and web fetch tools included by default
- Supports sub-agents converted from any Agent instance
Stirrup cons
- Web search requires separate BRAVE_API_KEY environment variable
- E2B cloud sandbox requires E2B_API_KEY and separate account
- Docker backend requires Docker daemon running and stirrup[docker] installation
- Local code execution runs with user permissions (security consideration)
- No built-in hosted solution - must self-host and manage infrastructure
- LiteLLM support requires optional stirrup[litellm] installation
- Browser tool requires optional stirrup[browser] installation
- MCP support requires optional stirrup[mcp] installation
- Learning curve for ToolProvider pattern and custom tool creation
Frequently asked questions about Stirrup
What is Stirrup and how is it different from other agent frameworks?
Stirrup is a lightweight, open-source framework for building AI agents that differs by working with the model instead of against it. Unlike rigid frameworks that impose strict workflows that can degrade output quality, Stirrup lets models choose their own approach to completing tasks (similar to Claude Code). It incorporates best practices from leading agents like Claude Code and Codex, including context management, foundational tools like code execution, and MCP support, while remaining fully customizable.
How do I install Stirrup?
Install the core framework with 'pip install stirrup' or 'uv add stirrup'. For all optional components, use 'pip install stirrup[all]' or 'uv add stirrup[all]'. You can also install individual extras: 'pip install stirrup[litellm]' for LiteLLM support, 'pip install stirrup[docker]' for Docker code execution, 'pip install stirrup[e2b]' for E2B cloud sandboxes, 'pip install stirrup[mcp]' for MCP integration, or 'pip install stirrup[browser]' for browser tools.
What tools are included by default?
When you create an Agent without specifying tools, it uses DEFAULT_TOOLS which includes: LocalCodeExecToolProvider (provides 'code_exec' tool for executing shell commands in an isolated temp directory) and WebToolProvider (provides 'web_fetch' and 'web_search' tools for fetching web pages and searching the web). Web search requires a BRAVE_API_KEY environment variable to function.
What code execution backends are available?
Stirrup provides three code execution backends: LocalCodeExecToolProvider executes in an isolated temp directory on the host machine (good for development and trusted code), DockerCodeExecToolProvider executes in a Docker container for better isolation (production, semi-trusted code, requires stirrup[docker] and Docker daemon), and E2BCodeExecToolProvider executes in E2B cloud sandboxes for maximum isolation (production, untrusted code, requires stirrup[e2b] and E2B_API_KEY).
Which LLM providers does Stirrup support?
Stirrup has built-in support for OpenAI-compatible APIs (OpenRouter, DeepSeek, vLLM, Together AI, etc.) via ChatCompletionsClient, and LiteLLM support for Anthropic Claude, Google, and other providers via LiteLLMClient (requires stirrup[litellm]). You can also bring your own client by implementing the LLMClient protocol. Models like gpt-5, claude-sonnet-4.5, deepseek-chat, and deepseek-reasoner are all supported.
How does context management work in Stirrup?
Stirrup automatically summarizes conversation history when approaching context limits to stay within token bounds while preserving task fidelity. The context_summarization_cutoff parameter (default 0.7) controls at what percentage of the context window summarization triggers. This happens automatically during the agent loop, so you don't need to manually manage context size.
How do I create custom tools?
Create a custom tool by defining a Pydantic model for parameters, writing an executor function that returns ToolResult, and wrapping it in a Tool object with name, description, parameters, and executor. For example, define GreetParams as a Pydantic model, write a greet function returning ToolResult[ToolUseCountMetadata], then create GREET_TOOL = Tool(name='greet', description='...', parameters=GreetParams, executor=greet). Add it to your agent with tools=[*DEFAULT_TOOLS, GREET_TOOL].
What is the skills system?
Skills are modular, domain-specific instruction packages that extend agent capabilities. Pass a skills_dir to agent.session() to make skills available. The agent receives a list of available skills in its system prompt and can read full instructions via 'cat skills/<skill_name>/SKILL.md'. This allows you to add domain expertise without modifying the core framework or retraining models.
How do sub-agents work?
Convert any agent into a tool using agent.to_tool() to enable hierarchical agent patterns. Create specialized worker agents with their own tools and system prompts, then convert them to tools for a supervisor agent. For example, create a research_agent with web tools and max_turns=5, convert it with research_subagent_tool = research_agent.to_tool(description='...'), then use it in supervisor_agent = Agent(tools=[research_subagent_tool, writer_subagent_tool]).
Is Stirrup free or does it cost money?
Stirrup is completely free and open-source with no paid plans or subscription fees. It's available on PyPI and GitHub. You only pay for the LLM API calls you make through your chosen provider (OpenRouter, OpenAI, Anthropic, etc.). Some optional backends require separate service accounts (E2B for cloud sandboxes, Brave for web search), but the framework itself has zero cost.