stirrup

What it is and what it does

Stirrup is a lightweight agent framework designed to work with language models rather than impose rigid workflows on them. It provides a foundation for building autonomous agents that can execute code (locally, in Docker, or E2B sandboxes), search and fetch web content, call external tools via MCP servers, process files, and incorporate human feedback. The framework includes built-in context management to handle long conversations, multimodal support for images and video, and a flexible tool system based on Pydantic schemas.

The package ships with sensible defaults—local code execution and web search tools—but is fully customizable. You can use it as an installed package or fork it as a template for building specialized agents. It supports multiple LLM providers through OpenAI-compatible APIs, LiteLLM, or custom clients, and includes a skills system for modular, domain-specific instruction packages. The 11 runtime dependencies cover HTTP requests, image and video processing, schema validation, and retry logic.

Use it for:

• Build an autonomous research agent that searches the web, fetches articles, and synthesizes findings into a report
• Create a code-generation agent that writes, tests, and refines scripts based on user requirements
• Develop a data analysis agent that processes files, executes analysis code, and generates visualizations
• Set up a multi-tool agent that integrates with external services via MCP to automate complex workflows
• Prototype a specialized agent by cloning the repository and customizing the core loop and tool set

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Stirrup is a lightweight Python framework for building LLM-powered agents that can execute code, search the web, process files, and call external tools with minimal scaffolding.

Yes. Stirrup is actively maintained, has low install friction, carries a permissive MIT License, and addresses a real need for a lightweight, unopinionated agent framework. Its 548 GitHub stars and recent activity suggest community traction. No known security vulnerabilities. Best suited for developers building agents who want flexibility over rigid frameworks.

Install

stirrup on PyPI

pip install stirrup

uv add stirrup

poetry add stirrup

Installing stirrup

Before you install

Low friction installation with a pure Python wheel. Active maintenance—last commit 2026-08-05, released 2026-08-04—and 548 repository stars suggest ongoing development. Requires Python 3.12 or later.

License in practice

MIT License permits unrestricted use, modification, and redistribution with minimal restrictions, making it suitable for both commercial and open-source projects.

Quickstart

pip install stirrup

import asyncio
from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient

async def main():
    client = ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-opus-5",
        max_tokens=8_192,
        context_window_tokens=1_000_000,
    )
    agent = Agent(client=client, name="agent", max_turns=15)
    async with agent.session(output_dir="./output") as session:
        finish_params, history, metadata = await session.run("Your task here")

asyncio.run(main())

Requires Python 3.12 or later. API key environment variable (OPENROUTER_API_KEY or equivalent for your provider) must be set before running.

Verify before relying

• Whether all 11 runtime dependencies are required for core functionality or only for optional features like video processing or web search
• Performance characteristics and latency when running agents with many tool calls or long conversation histories
• Compatibility scope with LLM providers beyond OpenAI-compatible APIs and LiteLLM

Package facts

Evidence: stirrup-0.2.0-py3-none-any.whl

Keywords: ai, agent, llm, openai, anthropic, tools, framework

Tags

More Python Modules packages

Further reading