# Stirrup: a tool constant removed for being shared, and two extras the readme skips

> Stirrup is a small Python framework for building agents, positioned as unopinionated in a specific way: it does not impose a workflow, it takes the practices it borrows from leading coding agents, and it leaves the loop shape to the model. Its documentation is unusually candid about one API decision, and the packaging has two small gaps worth knowing before you install.

**ArtificialAnalysis/Stirrup** — The lightweight framework for building agents

- Repository: https://github.com/ArtificialAnalysis/Stirrup
- Website: https://stirrup.artificialanalysis.ai
- Stars: 643 · Forks: 61
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/artificialanalysis-stirrup

## A constant was removed from the API because it was shared

The most useful paragraph in this documentation is a breaking change notice, and it explains a concurrency bug rather than a redesign. There used to be a list of default tools that callers passed into the agent. It was removed because every caller who passed it shared the same two provider instances, and those instances are stateful: one holds a temporary directory for code execution, the other holds an HTTP client. Sharing them across concurrent sessions means two runs writing into one temporary directory. The replacement is a function that returns fresh provider instances on every call, and the migration instructions cover both shapes of the old call, including the case where you had appended your own tool to the constant. This is the kind of note most projects put in a changelog and nobody reads; here it is in the tool documentation, which is where you would look when your runs start interfering with each other.

## You declare the model's context window by hand

Context management is built in, and how it works starts with a value you supply rather than one the framework discovers. The client constructor takes a context window size alongside the maximum output tokens, and the examples pass a very large window with a modest output cap. The framework's job is then to notice when the conversation approaches that declared limit and summarise the history automatically. Two things follow. If you set the window optimistically for a model that actually has less room, the framework will summarise later than it should, and the failure will surface as a provider error rather than a graceful compaction. If you set it too low, you will be summarising conversations that would have fit. It also means context management here is a policy you configure rather than a behaviour you inspect, so it is worth setting the number from the model's real documentation rather than from the largest value you have seen in an example.

## The readme documents five extras, the manifest defines seven

Installation comes in three shapes: the core package, everything at once, and individual extras. The readme lists five extras by name, covering the alternative model client, container code execution, hosted sandbox execution, protocol client support and browser automation. The packaging metadata defines seven, because two more exist that the readme never mentions. One adds a rate limiter on top of the hosted sandbox extra, which is the combination you actually want if you are running many sessions against a service that bills per call. The other adds a chat platform bot. So a reader who installs from the readme's list and then tries to follow an example involving a bot will find the extra exists but undocumented. The aggregate extra does include it, so the all-in-one install hides the gap entirely, which is why the mismatch survives. The documented five are installed like this:

```bash
pip install stirrup
pip install 'stirrup[all]'
pip install 'stirrup[litellm]'
pip install 'stirrup[docker]'
pip install 'stirrup[e2b]'
pip install 'stirrup[mcp]'
pip install 'stirrup[browser]'
```

The same lines are offered as equivalents for the uv add command, and the editable install used when you clone the repository to build your own agent takes the same extras in the same bracket form.

## The declared platforms are macOS and Linux

The metadata classifiers name two operating systems, a Mac one and a Linux one, and both Python versions the project supports, plus a typed-marker classifier and a beta development status. Windows is not among them. That is worth weighing against the rest of the framework, which is otherwise portable: the core client is an HTTP call, the tools are a generic interface, and the code-execution backends are a local shell, a container client and a hosted sandbox API, none of which is intrinsically platform-bound. The omission reads more like an untested platform than a hard refusal, particularly because a chat-bot extra is provided and bots tend to run wherever the team does. If you are on Windows, the honest position is that the framework does not claim support, and the local code-execution backend in particular is the piece most likely to need work there.

## The core dependencies are the media pipeline and the tool bridge

Eleven core dependencies, and the list tells you what the framework actually does rather than what it advertises. Two of them are for media: one library for video and audio handling and one for images, which together produce the automatic format conversion the feature list claims. One detects file types, which is what lets document input work without a user declaring extensions. One extracts readable text from web pages rather than handing the model raw markup, which is the difference between a usable fetch and a token bill. One converts a JSON schema into Pydantic models, and that is the mechanism behind both the generic tool interface and the protocol client, where a server's declared schema becomes a validated parameter set for free. The remainder are infrastructure: an async runtime, an HTTP client, the model client, validation, retry logic and terminal output.

## Fifteen examples, and a skills directory at the root

The repository carries more examples than documentation pages, and the example names are a usable index of what the framework supports. There is a getting-started file, a custom tool file, a user-input file that demonstrates the human-in-the-loop tool, a sub-agent file, an image-viewing file, a browser-automation file built on a browser-use dependency, a protocol client file, an alternative-responses-client file, examples for two model providers reached two different ways, one for each code-execution backend including the hosted sandbox, a chat-bot file, a skills directory, a code-executor directory and a calculator example that exists to show the web tools. A skills directory also sits at the repository root rather than inside the examples, which tells you the modular instruction package system is a first-class feature of the framework rather than an example of one.

## Seven keys in the environment file, and one that only degrades

The repository ships an example environment file that groups its variables by purpose rather than alphabetically, and the grouping is a description of the runtime. Three keys belong to the standard chat completions client, which reads a specific one by default and accepts an explicit key for any OpenAI-compatible endpoint, and two more belong to the alternative client, which is the one that needs a different provider's key. A sixth is marked required for the search tool, and the quick start says the agent still runs without it with web search simply unavailable. That is the only variable in the file described as soft-failing rather than hard, and it is worth knowing before you conclude your setup is broken. The seventh is the sandbox key, marked required for the sandbox execution backend. So of the three code-execution locations the feature list advertises, only one has an environment variable, and the other two need none.

## Conclusion

Stirrup suits someone who has been held back by a framework that forces a workflow and wants the loop, the tools and the model client to be theirs to choose. Before you build on it, read the tool provider section rather than skipping it, because the default-tool call returns fresh instances on purpose and sharing them across concurrent sessions is the mistake the project already made once. Decide which execution backend you need and install the matching extra, since local, container and hosted sandbox code execution are three different dependencies. And note that the declared platform classifiers do not include Windows even though the framework ships a chat-bot extra.

## FAQ

### What does Stirrup do differently from other agent frameworks?

It does not impose a workflow: the agent loop runs until a finish tool is called or the turn limit is reached, and the model chooses its own approach. The practices behind the default tools were taken from analysing leading coding agents rather than invented.

### Why was the DEFAULT_TOOLS constant removed?

Because every caller passed the same two provider instances, and those hold per-session state such as a temporary directory and an HTTP client, so concurrent runs interfered. Call default_tools() instead, which returns fresh instances each time.

### Where can Stirrup run code?

Locally in an isolated temporary directory, inside a container through the container extra, or in a hosted sandbox through the sandbox extra, which needs its own key. There is also a throttle extra that adds a rate limiter on top of the sandbox.

### Does Stirrup support Windows?

The metadata classifiers name only MacOS and POSIX Linux. The documentation does not claim Windows support, so anyone on it is running an untested combination, most likely around the local code-execution backend.

## Sources

- [ArtificialAnalysis/Stirrup on GitHub](https://github.com/ArtificialAnalysis/Stirrup)
- [License: MIT](https://github.com/ArtificialAnalysis/Stirrup/blob/main/LICENSE)
- [Project website](https://stirrup.artificialanalysis.ai)
- [README](https://github.com/ArtificialAnalysis/Stirrup/blob/main/README.md)
- [Releases](https://github.com/ArtificialAnalysis/Stirrup/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/artificialanalysis-stirrup