# cayu: treating agent side effects as runtime contracts

> cayu is a Python framework and runtime for domain-specific long-horizon agents, built around durable sessions, approval gates before side effects, spend caps checked before each model call, and multi-agent collaboration. It targets teams whose agents do consequential work, not demo scripts.

**cayu-dev/cayu** — Cayu is an open-source Python framework for building and running domain-specific long-horizon agents, with a durable runtime built in.

- Repository: https://github.com/cayu-dev/cayu
- Website: https://cayu.dev/
- Stars: 805 · Forks: 76
- Language: Python
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/cayu-dev-cayu

## Built for failures at the boundary, not for the happy path

The pitch is narrow and worth reading twice. Cayu is described as a Python runtime for long-running agents: durable sessions that survive restarts and redeploys, human approval before side effects, spend caps enforced before each model call, and multi-agent collaboration.

The reasoning is in the section titled Why Cayu, which lists the failures it says production systems hit. A process dies after a side effect but before state is recorded. A model requests a valid tool with the wrong authority. A run needs human input halfway through. Context grows until a provider rejects the next request. Retries, forks or subagents lose cost and causal attribution. Operators cannot reconstruct what happened from prompt text alone. Evals test final prose while missing the runtime trajectory.

That list is the product. Cayu's stance is that these are runtime contracts rather than application concerns, so important actions become structured events, tool authority and recovery are explicit, and configured durable stores let transcripts and checkpoints survive process boundaries.

## Framework, harness, runtime and agent are four different things

The README draws a line that many agent frameworks blur, and it is worth keeping in mind while reading the rest of the documentation.

A framework is Cayu's Python APIs, components and defaults. A harness is the domain-specific system you assemble yourself from context, tools, memory, policies, domain logic and verification. A runtime is the framework's execution machinery for sessions, state, authority, workers, budgets and recovery. An agent is the resulting application that performs a defined job. Cloud is the optional deployment and shared operation of agents built with the framework.

The split matters for ownership. The README states plainly that applications own their user interface, authentication, business authorization, domain rules and completion criteria. Cayu does not take over those. What it supplies is the execution layer beneath them, and the repository layout with its `src` directory, `tests`, `examples`, `dashboard` and `docs` folders is consistent with that division. A public concepts and source map is linked from the README for anyone who wants to see which component does what.

## Session stores and resume requests, in SQLite or Postgres

The first row of the capability table is where durability lives. Durable sessions and recovery map to `SQLiteSessionStore` or `PostgresSessionStore` in `cayu.storage`, combined with `ResumeRequest`, while `ExecutionProfilePolicy` in `cayu.runtime` governs what happens when a session resumes on a new build.

The design decision here is that resume is a policy question, not an automatic consequence of persisting state. If a build changed in a way that makes an old checkpoint unsafe to continue, an execution profile policy is the place to say so. That is a real difference from frameworks where a restart simply replays a transcript.

Around that, the runtime contract list in the README names durable sessions, transcripts, events, checkpoints, resume and interruption, then controlled tool effects, policies, approvals and idempotency identities, human-input checkpoints, approval resolution and manual recovery, task dispatch, worker ownership, resumable workflows and child-session lineage, usage accounting, run limits, budgets, pricing and causal attribution, and execution admission, recovery and reconciliation of uncertain external effects.

The last item is the one to remember. Reconciliation of uncertain external effects is what closes the gap the README opened with, where a process dies after a side effect but before state is recorded.

## Tool authority, approval tiers and spend caps

Approval before side effects is handled by `ToolPolicy`, which can return `ToolPolicyDecision.REQUIRE_APPROVAL` from `cayu.tools`, and the decision is then resolved through `cayu.approvals`. In other words, approval is a policy return value in the tool layer, not a wrapper the application writes around each call. The example directory contains a file named `business_approval_tiers.py`, which suggests tiers of approval are an intended configuration axis rather than a single on or off switch.

Money is handled separately and earlier. `BudgetLimit` is a per-request value and `BudgetPolicy` is a per-app value, both in `cayu.budgets`, and the README states they are checked before each model call. Checking before the call rather than after the response means an agent that is about to exceed a cap is stopped while the decision is still cheap, which is the only place a cap can actually bind.

Side effect control is reinforced elsewhere in the same runtime list through idempotency identities, controlled tool effects and manual recovery. The README also draws a trust boundary clearly: native Python tools are trusted application code, while configured isolation and external receipts determine the guarantees at the application boundary. Whatever isolation you configure is what your operators can rely on.

## Installing the package and its runtime dependencies

The README excerpt does not document an install command, so the packaging metadata is the place to read what you are getting. The project name is `cayu` and the build backend is hatchling:

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "cayu"
version = "0.12.0"
description = "Python runtime for long-running agents: durable sessions that survive restarts, human approval before side effects, spend caps, and multi-agent collaboration."
readme = "README.md"
requires-python = ">=3.11"
license = { text = "Apache-2.0" }
```

The runtime dependency list is short and mostly infrastructure:

```toml
dependencies = [
  "anyio>=4.14.2",
  "certifi>=2024.0",
  "cryptography>=42",
  "httpx>=0.27",
  "jsonschema>=4.23",
  "pydantic>=2.12",
  "referencing>=0.35",
  "typing-extensions>=4.14.1",
  "tzdata>=2024.0; sys_platform == 'win32'",
]
```

Pydantic and jsonschema carry the validation and structured output path, httpx the transport, and anyio the async runtime. Optional extras exist for other toolchains, including `claude-agent-sdk==0.2.168` and `codex = ["openai-codex==0.163.0"]`, which tells you the provider adapters are optional integrations rather than hard dependencies. Supported interpreter versions are listed in the classifiers:

```toml
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
```

The `uv.lock` file at the top level of the repository is consistent with a lockfile based workflow.

## Why the team moved off SDKs and graph frameworks

The README names its predecessors directly, which is unusual and useful. The team says it began by building agents with SDKs and frameworks including the Claude Agent SDK, Mastra and LangGraph, and that these helped implement the model-and-tool loop quickly. The stated problem was that production quality required deeper control of the loop itself: context assembly, model and tool invocation, output validation and failure handling.

The difference in approach is therefore one of where the guarantees live. Those frameworks get you to a working loop, and the loop is the product. Cayu keeps the loop in Python but moves the interesting guarantees into the runtime layer: schedules, durable state, credentials, execution environments, human intervention, recovery, cost attribution and evaluation.

Two constraints keep it from being a general purpose workflow tool. The README states that Cayu is Python only and is not a graph DSL, with agents, tools and workflows being ordinary Python. It also states that it is not only a hosted service, and that you can run it on your own infrastructure or deploy to the optional Cayu Cloud. If you want your graph defined as data, or if a hosted control plane is a requirement rather than an option, neither fits.

## Subagents, participants and durable peer requests

Multi-agent work maps to `SubagentTool` in `cayu.tools`, plus forks and participants with durable requests in `cayu.collaboration`. The distinction between a fork and a participant is worth noting, because the README also lists child-session lineage as part of the runtime contract, meaning a tree of sessions can be traced back to the parent that started it.

Durable requests are the part that differs from an in-process call. A request between agents that survives a restart is a different thing from a coroutine handing over a value, and the README lists task dispatch, worker ownership and resumable workflows alongside it. Worker ownership is also how leases work in `cayu.tasks`, where `TaskStore` workers and `TaskSchedulePolicy` handle scheduled follow-ups.

The examples directory is a good guide to the intended scale of use. It contains an `asynchronous_session_forks` folder, a `collaboration` folder, a `cache_aware_research_council` example, `business_approval_tiers.py`, and a series of live and conformance scripts such as `_runner_conformance.py`, `_workspace_conformance.py` and `agent_snapshot_stateful_evaluation.py`. The naming suggests that the project expects you to verify the runtime behaviour rather than take it on trust.

## Apache-2.0 terms, a Beta classifier and quick release cadence

The licence field on the repository says Apache-2.0, and pyproject.toml records the same Apache-2.0 text, with a NOTICE file and a LICENSE file at the top level. Apache-2.0 is a permissive licence that carries an explicit patent grant and requires you to keep the notice in redistributions. The README states that Cayu is open source and that the framework is Apache-2.0 licensed, and the optional hosted offering is a separate commercial path rather than a closed version of the runtime.

The classifiers label the project as `Development Status:: 4 - Beta`, which is an honest signal that the API may still move. The repository has no separate release notes file for you to diff, but the release history shows v0.11.1 on 2026-10-12, v0.11.2 on 2026-10-14 and v0.12.0 on 2026-10-19, with the last push on 2026-10-21. That is a fast cadence for a project below 1.0, and it cuts both ways: fixes arrive quickly, and pinning matters if a minor bump changes a policy default.

For an operator, the practical cost is reviewing changes to `cayu.runtime`, `cayu.tools` and `cayu.budgets` between versions, because those modules decide when a run spends money and when it needs a human.

## Conclusion

Adopt cayu when your agent performs consequential, restartable work on infrastructure you control and you need approval gates, budget enforcement and durable transcripts to be runtime behaviour rather than application code. Skip it if you want a graph DSL, a hosted only service, or support for Python below 3.11. Verify first that the `cayu.storage`, `cayu.tools`, `cayu.budgets` and `cayu.tasks` modules cover your specific failure modes, and confirm your own isolation policy for tool effects. The licence field on the repository says Apache-2.0, the last push was on 2026-10-21, and version 0.12.0 is classified as Beta.

## FAQ

### What is cayu and what is it used for?

Cayu is an open source Python framework and runtime for building and running domain-specific long-horizon agents. It provides durable sessions that survive restarts and redeploys, human approval before side effects, spend caps checked before each model call, and multi-agent collaboration.

### Which Python versions does cayu support?

pyproject.toml sets `requires-python = ">=3.11"`, and the classifiers list Python 3.11, 3.12, 3.13 and 3.14. The build backend is hatchling and the distribution name is `cayu`.

### How does cayu handle approvals before a tool runs?

A `ToolPolicy` in `cayu.tools` can return `ToolPolicyDecision.REQUIRE_APPROVAL`, and the decision is resolved through `cayu.approvals`. Approval is therefore a policy value in the tool layer rather than a wrapper written by the application.

### How are spend caps enforced in cayu?

A `BudgetLimit` per request and a `BudgetPolicy` per app live in `cayu.budgets`, and the README states they are checked before each model call. Usage accounting, run limits, pricing and causal attribution are also part of the runtime contract list.

### Is cayu a hosted service or can I self-host it?

The README states that Cayu is not only a hosted service and that you can run it on your own infrastructure, or deploy to the optional Cayu Cloud. Applications also own their own user interface, authentication and business authorization.

### What licence is cayu released under?

The licence field on the repository says Apache-2.0, and pyproject.toml lists the same licence text. The project classifiers describe the package as Beta at version 0.12.0.

## Sources

- [cayu-dev/cayu on GitHub](https://github.com/cayu-dev/cayu)
- [License: Apache-2.0](https://github.com/cayu-dev/cayu/blob/main/LICENSE)
- [Project website](https://cayu.dev/)
- [README](https://github.com/cayu-dev/cayu/blob/main/README.md)
- [Releases](https://github.com/cayu-dev/cayu/releases)

---

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