---
title: "StatePilot · Deterministic state-machine guards for"
description: "Deterministic state-machine guards for AI-agent workflows. Enforces the allowed tool order, transitions, loop limits, and cost budgets at runtime. Fail-closed,"
canonical: "https://matthiasmeyer.tech/repos/statepilot"
language: "en"
last_updated: "2026-08-01"
markdown_versions: ["https://matthiasmeyer.tech/repos/statepilot.md", "https://matthiasmeyer.tech/de/repos/statepilot.md", "https://matthiasmeyer.tech/es/repos/statepilot.md"]
image: "https://matthiasmeyer.tech/api/og/repo/statepilot?lang=en"
publisher: "Matthias Meyer, https://matthiasmeyer.tech (llms.txt: https://matthiasmeyer.tech/llms.txt)"
---

agents stable Python

# StatePilot

Deterministic state-machine guards for AI-agent workflows

Enforces the allowed tool order, transitions, loop limits, and cost budgets at runtime. Fail-closed, so an agent cannot step outside its declared state machine. Zero-dependency core, LangGraph-aware. 74 tests, MIT, Python.

[View on GitHub →](https://github.com/studiomeyer-io/statepilot)[PyPI](https://pypi.org/project/statepilot/)

## What it solves

A recurring theme in agent tooling is wrapping a non-deterministic model in deterministic code, and the reason is simple: prompting an agent to only call these tools, in this order is a request, not a rule. It holds until it does not. statepilot turns that request into a state machine that the runtime enforces.

## How it works

You define the machine, and at runtime it decides which tools the agent may call and in which order. Around that sit the guards that catch the failure modes you actually see: loop detection for the agent that keeps retrying the same step, a cost budget, and a hard cap on the number of steps. Anything the machine does not allow raises rather than silently proceeding. The core has zero runtime dependencies, is fully typed, and needs Python 3.10 or newer.

## When to use it

It fits a workflow whose steps you can actually name: an intake that has to happen before a lookup, a payment that must not run twice, an escalation that only fires after a check. That is where a state machine is a description of the work rather than a cage around it.

## When not to use it

Open-ended work is the wrong fit. If you cannot draw the states in advance, you will spend more time widening the machine than you save by having it, and every widening is a hole. Exploration, research and anything where the next step depends on what the last one found belong outside it.

Stars

★ 0

installs

↓ 20

Clones (14d)

⊟ 12

Language

Python

Updated

2026-08-01

## Install

```
pip install statepilot
```

## Related repos

- Agent Fleet

    → guards the tool flow of

    →

    https://matthiasmeyer.tech/repos/agent-fleet

- Darwin LangGraph

    → runtime guardrails for

    →

    https://matthiasmeyer.tech/repos/darwin-langgraph

## Sitemap

Every page of this site as Markdown: [sitemap](https://matthiasmeyer.tech/sitemap.md). Curated entry point: [llms.txt](https://matthiasmeyer.tech/llms.txt).