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. 1.0 means every run can be recorded, replayed offline, forked, diffed, and frozen into a regression test — with a written stability contract.

Site: readyagents.dev. Repo: github.com/readyagentsdev/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. Install with pip install readyagentsdev, or from this clone.

60-second start

Requires Python 3.11–3.14 on Linux, macOS, or Windows. Current version is 2.0.0. Install with pip install readyagentsdev, or from this clone.

git clone https://github.com/readyagentsdev/readyagents-core.git
cd readyagents-core
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
readyagents run examples/calc_pipeline.yaml
readyagents runs list
readyagents doctor

readyagents run examples/calc_pipeline.json is the same graph.

Or from PyPI (the wheel does not ship examples/):

pip install readyagentsdev
readyagents new my-flow

HITL next: docs/first-ten-minutes.md.

What it does

• Define agent workflows as YAML or JSON (nodes + edges)
• Run agent, tool, condition, transform, approval, parallel, include, foreach, a2a, memory, and code 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)
• Record, replay offline, fork, diff, and freeze a run into an eval fixture (time machine)
• Optional agent firewall: taint, tool policy, MCP pinning (security model, policy) — defence in depth, not a solution to prompt injection
• Scaffold a starter: readyagents new my-flow (basic, approval, research, pipeline, review, foreach, agent-tools, gated)
• Builtin tools with zero extra servers: now, calc, json_get, list_dir, read_file, write_file, optional http_get
• Small governed connector set (rest, sql, object_storage, message, ingest) plus readyagents connectors catalog — connectors
• Optional MCP client and server (readyagents mcp serve, readyagents mcp probe) with official tasks and MRTR approvals
• Optional A2A serve/probe and type: a2a delegation (Unreleased on this checkout; 0.3 JSON-RPC projection; remote content untrusted; not certification)
• Optional memory (type: memory, local JSON/SQLite, BM25, TTL/forget) — Unreleased on this checkout; untrusted; delayed injection and scope escape first; not a quality claim
• Optional sandboxed code (type: code, subprocess default) — Unreleased; accident-grade isolation, not hostile-code-proof; no bundled container runtime
• Optional output contracts (contract: on a value-producing node) — Unreleased; declared schema and content rules, not a safety classifier
• Optional multi-agent teams (type: team) — Unreleased; closed members, engine-enforced stop, no routing-quality claim
• Optional workflow studio (readyagents studio) — Unreleased; loopback canvas and run inspector; YAML on disk stays the source of truth; not a hosted product
• Optional model routing (routing:, Gemini/Bedrock/Vertex extras, readyagents models) — Unreleased; declared policy, not quality inference; no-policy selection unchanged
• Optional multimodal I/O (MediaPart, type: document, type: transcribe, image/pdf/audio extras) — Unreleased; plumbing and governance, not extraction accuracy; text-only runs unchanged
• Optional knowledge pipelines (type: ingest, readyagents knowledge) — Unreleased; citations and freshness, not a retrieval-quality claim; plain memory writes unchanged
• Optional data pipelines (type: table, type: classify, readyagents table) — Unreleased; deterministic ops and remainder-only classify; not a warehouse; json_get/foreach defaults unchanged
• Optional long-horizon waits (type: wait, readyagents wake / event) — Unreleased; lazy wake, no daemon; waiting ≠ paused; not a scheduler
• Optional event triggers (triggers:, readyagents triggers) — Unreleased; core contract only, no listener in core; at-least-once plus idempotency, not exactly-once; loopback-default webhook
• Optional agent skills (type: skill, readyagents skills / agents-md) — Unreleased; open SKILL.md format; untrusted instructions; sandbox scripts; not a marketplace
• Optional workflow packaging (readyagents package) — Unreleased; review-before-install archives with policy, fixtures, and signature; signed static index; not a hosted marketplace
• Optional simulation (readyagents simulate) — Unreleased; declaration-driven cases, honest coverage, dry-run default; not exhaustive, not a hosted simulator
• Optional self-healing (readyagents health, recovery:) — Unreleased; fingerprints and fail-safe gates; not prediction; not a hosted reliability service
• Optional benchmark harness (readyagents bench) — Unreleased; offline cassettes, labelled engine vs live timing; not a model-quality or competitor ranking
• Optional prompt optimization (readyagents optimize, readyagents prompts) — Unreleased; versioned prompts, offline reflective loop, gated promotion; not GEPA/DSPy parity; YAML that never optimizes is unchanged
• Optional feedback export (readyagents feedback export|stats) — Unreleased; consent-gated corrections as eval/sft/dpo; not fine-tuning; not a hosted dataset
• Optional governed browser use (type: browser) — Unreleased; declared actions, allowlist, taint, offline replay; driver in an optional pack; no CAPTCHA solving; not a free-running browser agent
• Optional conversational sessions (type: converse, readyagents sessions, serve chat) — Unreleased; turns are durable runs; loopback chat; no audio in core; not a hosted chat product
• Optional environments and rollout (readyagents.env.yaml, run --env, promote, rollback, env status|history|diff) — Unreleased; pinned signed releases, gated promote, canary/shadow, lazy rollback; not a hosted deploy
• Optional migration importers (readyagents import) — Unreleased; n8n / LangGraph / CrewAI / trigger-action; structural translation plus a fidelity report; never exec source Python; not behavioural equivalence
• Optional agent registry (readyagents registry) — Unreleased; inventory from declared roots; derived facts plus declared roles/tier; draft Annex VIII export, not a legal filing; not a hosted registry
• Optional distillation (readyagents distill) — Unreleased; consented hashed splits, pack-owned training, holdout-gated one-node adapters; not a quality claim; core never trains
• Extra node types and tools via Python entry points (readyagents.packs)
• Per-node token/cost, budgets, --estimate / --max-spend caps, local spend ledger, model fallback, JSON logs
• External approval injection (readyagents decide) and outbound pause notify
• Secrets / RBAC / PII-redaction hooks and an append-only, hash-chained audit trail; readyagents evidence writes a local pack of a run — evidence, not legal compliance or certification (compliance)
• Pydantic output_schema on agent nodes; opt-in local LLM cache
• readyagents.testing helpers, recorded LLM mocks, and a tiny eval harness

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

• Why ReadyAgents?
• Getting started
• First ten minutes
• Concepts
• Configuration (BYOK)
• Workflows
• Authoring (JSON Schema, editors, located errors)
• Connectors (small catalog; write-shaped ops gate by default)
• Sovereign mode (in-process egress refuse, not an OS sandbox)
• Cost / TokenOps (informational vs the provider invoice)
• Time machine (record / replay / fork / diff / freeze)
• MCP
• A2A (untrusted remote content; delegation can exfiltrate; not certification)
• Memory (untrusted; delayed injection and scope escape; not a quality claim)
• Scale and batch (opt-in; Unreleased; not a distributed worker; benchmarks are not a marketing claim)
• Streaming (opt-in --stream; Unreleased; not audio)
• Guardrails / output contracts (opt-in contract:; Unreleased; declared rules, not a safety claim)
• Multi-agent teams (opt-in type: team; Unreleased; closed members; no quality claim)
• Model routing (opt-in routing:; Unreleased; declared policy, not a quality claim)
• Multimodal I/O (opt-in MediaPart / type: document / type: transcribe; Unreleased; extras; not an OCR claim)
• Knowledge pipelines (opt-in type: ingest; Unreleased; citations/freshness; not a retrieval-quality claim)
• Data pipelines (opt-in type: table / type: classify; Unreleased; not a warehouse)
• Long-horizon waits (opt-in type: wait; Unreleased; lazy wake; not a scheduler)
• Event triggers (opt-in triggers:; Unreleased; no listener in core; at-least-once plus idempotency)
• Agent Skills (opt-in type: skill; Unreleased; open format; not a marketplace)
• Governed browser use (opt-in type: browser; Unreleased; declared actions; no CAPTCHA; optional pack)
• Conversational sessions (opt-in type: converse; Unreleased; loopback serve chat; no audio in core)
• Environments and rollout (opt-in readyagents.env.yaml; Unreleased; pinned releases; gated promote; not a hosted deploy)
• Migration (opt-in readyagents import; Unreleased; structural translation only)
• Agent registry (opt-in readyagents registry; Unreleased; declared roots; draft Annex VIII, not a filing)
• Distillation (opt-in readyagents distill; Unreleased; pack-owned training; holdout-gated adapters; not a quality claim)
• Packaging (opt-in readyagents package; Unreleased; review-before-install; not a marketplace)
• Simulation (opt-in readyagents simulate; Unreleased; not exhaustive; not a hosted simulator)
• Self-healing (opt-in readyagents health / recovery:; Unreleased; not prediction; not a hosted service)
• Benchmarks (opt-in readyagents bench; Unreleased; offline cassettes; not a quality ranking)
• Packs
• Supply-chain trust (signatures prove origin, not safety)
• Continuous pack (optional, separate distribution)
• Platform support
• CLI
• Compliance evidence (Articles 12–14 mapping; not certification)
• Observability
• Changelog
• Release notes 2.0.0

Install extras

LLM and MCP extras are optional.

pip install "readyagentsdev[openai]"
pip install "readyagentsdev[anthropic]"
pip install "readyagentsdev[gemini]"
pip install "readyagentsdev[bedrock]"
pip install "readyagentsdev[vertex]"
pip install "readyagentsdev[mcp]"
pip install "readyagentsdev[all]"
pip install "readyagentsdev[image]"
pip install "readyagentsdev[pdf]"
pip install "readyagentsdev[audio]"
pip install "readyagentsdev[table]"

From a clone, the same extras are pip install -e ".[openai]" (and anthropic / gemini / bedrock / vertex / mcp / all). The optional [otel] extra is not included in [all]; it starts no collector (see observability.md). The optional [sign] extra (Ed25519 artifact signatures), [jwt], [gemini], [bedrock], [vertex], [image], [pdf], [audio], and [table] extras are also not in [all]. Unsigned default runs never import them. Codecs are extras; core installs stay text-only. Pandas is optional for table ops; stdlib is sufficient.

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 are not in Core. The optional readyagents-pack-continuous distribution (separate repository, not a Core extra) can run configured workflows from an explicit foreground command. Installing Core still starts no scheduler or listener.

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. Public contact: info@readyagents.dev. Do not commit API keys. Local operator files such as .env are gitignored.