sovereign-agent

Sovereign Agent

An always-on AI agent you can read end to end, in Python.

Sovereign Agent runs Lucy’s ice cream shop unattended. It answers her messages, keeps stock, orders from suppliers within the spending she approved, survives a worker crash without ordering twice, and reports its day from receipts rather than from what the model said. Everything an agent harness needs is here, small enough to read: the model and tool loop, typed tools, durable SQLite state, memory with retrieval, versioned skills, a durable work queue, messaging and schedules, approvals bound to the exact spend, idempotent external actions, leases and fencing for recovery, execution isolation, evaluation, controlled improvement and bounded delegation. Python 3.12 or newer, including Google Colab, SQLite and one runtime dependency, Pydantic.

The optional research profile keeps revisable investigations, bounded scientific proposals, asynchronous fixture measurements and evidence history in the same agent lifecycle. The shop remains the teaching example; research roles extend it. An investigation outlives its execution allowance: later authorized sessions retain its evidence and cumulative accounting. The research CLI supports the approved Claude Code subscription route as well as explicitly configured HTTP model turns.

If it helps you understand how agents really work, star the repository: it is how other engineers find it.

Build it yourself, one chapter at a time

This repository is the finished agent. The way to understand it is to build it:

Read the book: Build Your Always-On AI Agent From Scratch on profrod.ai. Twenty chapters, each measuring its mechanism on real local models before building it.
Do the exercises: the book’s course in profrodai-resources. 38 ninety-minute notebook units that open in Colab, worked solutions, educator guides, and each chapter’s checkpoint code, which runs against this package.
Join the learner community: profrod.ai/community. Bring a result, a question or a failure you learned from.

Its final checkpoint runs a whole shop day: a separate simulated supplier loses replies, a worker is killed, and the agent verifies two purchases totaling USD 26.00 without a duplicate order.

git clone https://github.com/profrodai/profrodai-resources.git
cd profrodai-resources/courses/sovereign-agent-book
make setup run

For an initialized shop directory, sovereign-agent agent report --root PATH prints the current ledger-derived report. Amounts come from structured records, with uncertain outcomes and accounting disagreements made explicit.

Always-on means unattended work and explicit restart and recovery while the host and its dependencies are available. The book’s deployment chapter gives the one-host recipe. Maintained production organizations can graduate to Zeocore.

Install and run with uv

uv is the supported way to install and run sovereign-agent. Try it without installing anything permanent:

uvx sovereign-agent@latest doctor
uvx sovereign-agent@latest demo store --mode simulated --root /tmp/first-shift

(@latest makes uv refresh its cached tool environment, so you always get the current release.)

Or install the CLI onto your PATH:

uv tool install sovereign-agent
sovereign-agent doctor

(Plain pip install sovereign-agent still works in any Python 3.12 or newer environment, Google Colab included, if you prefer it.)

The 1.x API intentionally replaces the v0.7 fleet framework. To keep using that framework: uvx "sovereign-agent<1".

Educational development install

Python 3.12 or newer is required, the version Google Colab runs; uv provides it automatically.

uv sync
uv run sovereign-agent doctor

Expected result:

Sovereign Agent doctor
  Python:   3.12.x OK
  Pydantic: 2.x OK
  Network:  not required
  Tokens:   not required
  Providers:
    scripted available (streaming)
    claude   missing executable
    ...
Ready for the offline curriculum. Live providers are optional.

The runtime also provides a manually dispatched store-shift demo (no Pulse):

uv run sovereign-agent demo store --mode simulated

For additional runtime demonstrations, run the six advanced mechanisms with no provider, credential, or network:

uv run sovereign-agent mechanisms --root /tmp/sovereign-agent-mechanisms

This demonstrates four-plane isolation policy, durable condition scheduling, recoverable context compaction, session-incarnation fencing, bounded tool discovery, and provenance-bearing hybrid memory. The book at profrod.ai/book builds each of them from first principles.

Product vocabulary

Thing	Canonical word
Package and CLI	`sovereign-agent`
Control loop	`supervisor`
Installed OS hosting	`service`
Proactive wake	`pulse`
Liveness proof	`heartbeat` (records the runtime was alive; never creates work)
Intelligence CLI	`provider`
Governed identity	`actor`

An actor is not a model. Every provider receives the same governed assignment envelope and must emit a valid terminal event and write the exact ActorReport. A zero exit without both is a failed receipt. Cursor’s --workspace is directory selection, not sandboxing; isolation belongs to Sovereign Agent’s disposable workspace.

Provider subprocesses receive only base process variables plus documented credential allowlists: Claude (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN), Codex (CODEX_API_KEY), and Cursor (CURSOR_API_KEY). Other parent secrets are not forwarded.

Unit 1 gates

uv run python -m pytest -q
uv run python scripts/verify_runtime_dependencies.py
uv run python scripts/verify_source_budget_v2.py
uv run sovereign-agent --help
uv run sovereign-agent doctor

See the educational reset ruling and v0.7 migration guide.

Project resources

Keep building with Prof Rod

Found this material through a colleague, classroom or shared download? Get the complete book at profrod.ai/book and join the Prof Rod learner community. Bring one result, one question or one failure you learned from. Share this resource with another learner and keep its source links with it so they can find the full course and future updates.

This site is open source. Improve this page.