---
id: stirrup
version: "0.2.0"
license: MIT License Copyright (c) 2025 Artificial Analysis Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# stirrup — The lightweight foundation for building agents

License: permissive · Maintenance: active · Downloads: 241.1K/mo

## 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 above — 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

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

- License: MIT License Copyright (c) 2025 Artificial Analysis Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 241.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

llm agent framework, ai agent builder, code execution agent, autonomous agent framework, tool-calling agent library, multi-tool agent system, lightweight agent framework, agent-framework, llm-tools, async-first

[View on SkillFed](https://skillfed.io/packages/stirrup) · [View on PyPI](https://pypi.org/project/stirrup/)