ArtificialAnalysis/Stirrup

Stirrup – a lightweight foundation for building AI agents

What it is – Stirrup is a Python library that gives you a minimal, extensible scaffold for creating LLM‑driven agents. It deliberately stays out of the way of the language model, letting the model decide how to solve a task while providing a set of ready‑made “tools” (code execution, web search, file I/O, etc.) that the model can invoke.

Key ideas

Model‑first – unlike many frameworks that force a rigid plan‑and‑execute loop, Stirrup presents the model with a flexible toolbox and lets it choose the best sequence of actions.
Best‑practice defaults – the default tool set mirrors what the authors observed in leading agents (Claude Code, Codex), handling context summarisation, temporary directories, and tool lifecycles for you.
Plug‑and‑play – you can use the published stirrup package directly, or clone the repo and treat it as a template to build a completely custom agent stack.

Core features (as listed in the README)

Feature	What it gives you
Code execution	Run arbitrary code locally, inside Docker, or in an E2B sandbox.
Online search / web browsing	Search the web (via Brave API) and fetch pages for the model to read.
MCP client support	Connect to MCP servers to reuse external tools/resources.
Document I/O	Import files into the agent’s context and write output files.
Skills system	Bundle domain‑specific instruction sets as reusable “skills”.
Flexible tool interface	Define new tools by subclassing a simple `Tool` class with Pydantic‑typed parameters.
Human‑in‑the‑loop	A built‑in user‑input tool lets the model ask a human for clarification.
Context management	Automatic summarisation of conversation history when the token window is near its limit.
Provider‑agnostic LLM client	Pre‑built clients for OpenAI‑compatible APIs, LiteLLM, or any custom client you write.
Multimodal support	Handles images, video, and audio by converting them to a format the model can consume.

Quick‑start example (from the README)

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/example") as session:
        finish, history, meta = await session.run(
            "What is the population of Australia over the last 3 years? "
            "Search the web and create a simple matplotlib chart."
        )
        print(finish, history, meta)

if __name__ == "__main__":
    asyncio.run(main())

The snippet shows:

Creating a ChatCompletionsClient (OpenRouter in the example).
Instantiating an Agent with default tools (web search + local code execution).
Running a session that automatically handles tool lifecycles, logging, and file output.

Extending Stirrup

Add pre‑built tools – e.g., CALCULATOR_TOOL from stirrup.tools can be mixed with the defaults.
Define your own tool – write a Pydantic model for parameters, a function that returns a ToolResult, and wrap it in a Tool object.
Custom providers – implement a ToolProvider if your tool needs setup/teardown (e.g., a persistent DB connection).
Swap LLM back‑ends – use LiteLLMClient for Anthropic, Google, etc., or point ChatCompletionsClient at any OpenAI‑compatible endpoint (Deepseek, Ollama, etc.).

Installation

# Core package
pip install stirrup          # or: uv add stirrup

# All optional extras (Docker, E2B sandbox, browser, LiteLLM, MCP, etc.)
pip install 'stirrup[all]'

Individual extras can be installed separately (stirrup[docker], stirrup[browser], …).

When would you use Stirrup?

Prototyping a new agent – start with the default tools and a single LLM call, then iterate.
Building a domain‑specific assistant – add custom skills (e.g., finance calculators, medical lookup) without rewriting the execution loop.
Research on tool‑use patterns – the framework logs tool calls and automatically summarises context, making it easy to study how models interact with external resources.
Multi‑provider deployments – switch between Claude, Deepseek, Anthropic, etc., by swapping the client configuration.

Documentation & community

Full docs: https://stirrup.artificialanalysis.ai
Getting‑started guide, core concepts, examples, and tool‑creation tutorials are all hosted on the same site.
Development workflow uses uv, ruff, and pytest; the repo is MIT‑licensed.

Bottom line

Stirrup is a real, production‑ready Python framework for building LLM‑driven agents that need flexible tool use, context management, and easy swapping of LLM providers. It provides sensible defaults while staying lightweight enough to serve as a clean starting point for custom agent projects.