ReadyAgents Core

ReadyAgents is a free, self-hosted Apache-2.0 local one-shot agent workflow engine plus MCP toolkit: clone it, bring your own keys; always-on packs are waitlisted and not for sale.

Site: readyagents.dev. Repo: github.com/readyagents/readyagents-core.

Tried it? Open an I-ran-this issue. We are not launching. We are listening.

This repository is the free core. You keep the provider account and the bill. The package is not on PyPI. Install from this clone.

What it does

• Define agent workflows as YAML or JSON (nodes + edges)
• Run agent, tool, condition, transform, approval, parallel, include, and foreach nodes. Agent nodes may declare a tools: allowlist for a bounded tool-use loop.
• Persist after every node and resume a paused or failed run from the last successful node
• Inspect past runs: readyagents runs list / show / replay / report (local HTML)
• Scaffold a starter: readyagents new my-flow (basic, approval, research, pipeline, review)
• Builtin tools with zero extra servers: now, calc, json_get, list_dir, read_file, write_file, optional http_get
• Optional MCP client and server (readyagents mcp serve)
• Extra node types and tools via Python entry points (readyagents.packs)
• Per-node token/cost, budgets, model fallback, JSON logs
• External approval injection (readyagents decide) and outbound pause notify
• Secrets / RBAC / PII-redaction hooks and an append-only audit trail
• Pydantic output_schema on agent nodes; opt-in local LLM cache
• readyagents.testing helpers, recorded LLM mocks, and a tiny eval harness

60-second start

Requires Python 3.11+. Current version is 0.8.0. This package is not on PyPI. Install from this clone.

First-run clip: watch the 60-second run

git clone https://github.com/readyagents/readyagents-core.git
cd readyagents-core
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

This package is not on PyPI. Install only from the clone above.

Smoke test — no API keys:

readyagents run examples/calc_pipeline.yaml
readyagents runs list
readyagents runs report <run_id>

readyagents new my-flow
readyagents run examples/approval_gate.yaml --approve gate
readyagents run examples/composed_gate.yaml --approve gate
readyagents run examples/multi_gate.yaml --approve first --approve second

Human-in-the-loop without a decision pauses (exit 2, does not hang) and can be resumed:

readyagents run examples/approval_gate.yaml
readyagents runs list
readyagents resume <run_id> --approve gate
# or
readyagents resume <run_id> --reject gate
# or inject a JSON decision (no always-on webhook server in core):
readyagents decide <run_id> --file decision.json

With a key in .env (OPENAI_API_KEY or ANTHROPIC_API_KEY):

readyagents run examples/research_brief.yaml --input topic="agent workflows"

Architecture

flowchart LR
  YAML[Workflow YAML/JSON] --> Engine
  subgraph Core["ReadyAgents Core"]
    Engine[Workflow engine]
    Tools[Builtin tools]
    LLM[BYOK LLM providers]
    MCP[MCP client / server]
    Packs[Pack loader]
  end
  Engine --> Tools
  Engine --> LLM
  Engine --> MCP
  Packs --> Engine
  Packs --> Tools
  LLM --> OpenAI[OpenAI]
  LLM --> Anthropic[Anthropic]
  LLM --> Compat[OpenAI-compatible]

CLI

Examples (no keys unless noted)

Docs

• Getting started
• First ten minutes
• Concepts
• Configuration (BYOK)
• Workflows
• MCP
• Packs
• CLI
• Changelog
• Release notes 0.8.0

Install extras (still from this checkout)

LLM and MCP extras are optional. Install them from the cloned repo, not from PyPI:

pip install -e ".[openai]"
pip install -e ".[anthropic]"
pip install -e ".[mcp]"
pip install -e ".[all]"

Then cp .env.example .env and paste your own keys. Core workflows that only use builtin tools do not need extras, keys, or Node.js.

docker compose run --rm readyagents run examples/calc_pipeline.yaml
make smoke

What is not in this repository

Always-on packs are waitlisted and not for sale.

Always-on / continuous workers and schedulers. Hosted control plane. Hosted recovery and remote run stores. SSO, multi-tenant teams, billing.

The core has persist, resume, and approval pauses for a local one-shot. It does not run always-on.

License

Apache License 2.0. See LICENSE.

Security

Please report vulnerabilities as described in SECURITY.md. Do not commit API keys. Local operator files such as .env are gitignored.