ReadyAgents

ReadyAgents Core

ReadyAgents 可在本地运行 YAML Agent 工作流。每个节点都会保存检查点，因此运行可暂停以等待人工审批，从停止处继续，并离线重放作为回归测试。你的密钥，你的机器，无需守护进程。

网站：readyagents.dev。代码仓库：github.com/readyagentsdev/readyagents-core。

试用过？请提交 I-ran-this issue。我们并非要发布产品，而是在倾听。

此仓库是免费核心版。你自行保有服务提供商账户，并承担费用。使用 pip install readyagentsdev 安装，或从此克隆仓库安装。

60 秒快速开始

需要在 Linux、macOS 或 Windows 上运行 Python 3.11–3.14。当前版本为 2.0.12。使用 pip install readyagentsdev 安装，或从此克隆仓库安装。2 仅表示核心契约的版本；扩展各自有独立的成熟度等级。

pip install readyagentsdev
readyagents new my-flow
readyagents run my-flow/workflow.yaml
readyagents runs list

安装包也包含示例工作流，无需克隆仓库：

readyagents new f --from-example calc_pipeline
readyagents run f/workflow.yaml

readyagents new --list-examples 可显示所有示例。

也可以从克隆的仓库运行：

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 是同一张图。

接下来了解人在环路（HITL）：docs/first-ten-minutes.md。

功能

• 使用 YAML 或 JSON 定义 Agent 工作流（节点 + 边）
• 运行 agent、tool、condition、transform、approval、parallel、include、foreach 和 decide 节点。Agent 节点可通过 tools: 允许列表声明可用工具，以限制工具使用循环。type: decide 仍属实验性功能；参见 docs/decisions.md。
• 每个节点执行后都会持久化，并可从最后一个成功节点恢复暂停或失败的运行
• 检查以往的运行：readyagents runs list / show / replay / fork / diff / freeze / report（本地 HTML）
• 搭建入门模板：readyagents new my-flow（basic、approval、research、pipeline、review、foreach、agent-tools、gated、decide）
• 内置工具，无需额外服务：now、calc、json_get、list_dir、read_file、write_file
• MCP 客户端和服务端（readyagents mcp serve、readyagents mcp probe），支持官方任务和 MRTR 审批
• 策略、支出账本、预算和上限：每节点的 Token 和成本、--estimate / --max-spend 上限、模型回退、JSON 日志

除核心版外，同一次安装还提供 40 多个可选扩展——团队、Studio、浏览器、知识库、蒸馏、注册表、环境等。每个扩展及其成熟度等级和限制都列在 docs/extras.md 中。这些扩展都不是必需的，也不会改变核心版的行为。

Agent 防火墙（污点、工具策略、MCP 固定——安全模型、策略）是纵深防御，并不能解决提示词注入问题。

架构

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

命令	用途
readyagents init	如果 .env 不存在，则从 .env.example 写入
readyagents new [name] [--template basic|approval|research|pipeline|review|foreach|agent-tools|gated|decide] [--from-example NAME] [--list-examples]	搭建工作流、README、.env.example 和本地 JSON Schema，或复制随附示例
readyagents import SOURCE PATH [--out DIR] [--explain SOURCE]	导入 n8n / LangGraph / CrewAI / trigger-action 导出内容（仅进行结构转换）
readyagents validate PATH	对工作流进行 Schema 验证（失败时指出错误位置）
readyagents schema	打印、写入或检查生成的工作流 JSON Schema
readyagents eval PATH	对无需密钥的 fixture 套件评分（退出码为 0/1）
readyagents simulate PATH [...]	使用 eval 对声明驱动的案例评分；不同的失败会被冻结
readyagents optimize PATH --eval SUITE	针对你的 eval 套件进行反思式提示词优化
readyagents prompts list / show / history / diff / rollback	工作流旁的版本化提示词；回滚会精确恢复
readyagents env status / history / diff / deploy	已声明的环境和固定版本发布
readyagents registry scan / annotate / check / list / show / stats / card / export	根据已声明的根目录生成本地 Agent 清单（Annex VIII 导出为草案）
readyagents distill plan / dataset / train / evaluate / promote	根据获准使用的运行记录生成本地单节点适配器（pack 训练；必须提供 holdout）
readyagents promote PATH --from SRC --to DST	通过 eval/fixture/bench/health/approval 门禁后，将源固定版本复制到目标
readyagents rollback --env NAME	以原子方式恢复上一个版本；绝不自动前进
readyagents feedback export / stats	需经同意的数据集（生产数据）
readyagents run PATH [--input KEY=VALUE] [--dry-run] [--approve NODE] [--reject NODE] [--decision-file FILE] [--actor NAME] [--pack PATH] [--policy PATH] [--estimate] [--max-spend USD] [--max-tokens N] [--label KEY=VALUE] [--sovereign] [--stream] [--env NAME]	执行（或使用 --estimate 仅估算，不运行）。--env 会运行固定版本的发布内容。--stream 需显式启用
readyagents batch PATH --input-file FILE [--concurrency N] [--max-spend USD] [--out FILE]	前台运行：一个工作流处理多行 JSONL/CSV（需显式启用）
readyagents attest RUN_ID	数据驻留证明（技术证据，不代表符合法律规定）
readyagents bundle --out DIR	用于 pip install --no-index --find-links 的离线 wheel 集
readyagents resume RUN_ID [--approve NODE] [--reject NODE] [--decision-file FILE] [--policy PATH]	恢复已暂停或失败的运行
readyagents wake	评估等待条件（惰性运行；不会启动计时器或守护进程）
readyagents event	注入已签名事件（拒绝未签名事件）
readyagents policy check PATH	验证防火墙策略文件（默认拒绝）
readyagents policy explain PATH [--policy PATH]	显示每个节点可以调用哪些工具以及原因
readyagents evidence RUN_ID [--out DIR]	本地证据包
readyagents audit verify [--file PATH]	遍历哈希链式审计记录
readyagents spend [--since DATE] [--by day|workflow|model|actor|label]	TokenOps：汇总本地支出账本（仅供参考，与服务提供商账单可能不同）
readyagents graph PATH	确定性 Mermaid 路由（不执行任何操作）
readyagents decide RUN_ID [--file FILE | --node ID --decision approve] [--token-file JWT] [--actor NAME] [--reason TEXT]	注入批准；--actor 保持默认值，--token-file 用于标识
readyagents approvals list [--role ROLE] [--actor NAME] [--expiring-within 1h]	调用者可查看的暂停门禁队列
readyagents delegate --from A --to B --until TS [--scope ROLE]	有时间限制、仅单跳且可撤销的审批委托
readyagents delegations list | revoke ID	列出或撤销本地委托
readyagents identity verify --token-file JWT	根据本地信任锚验证断言
readyagents identity whoami	工作负载指纹（绝不显示私钥）
readyagents runs list	列出已持久化的运行
readyagents runs show RUN_ID	节点时间线和已存储状态（inspect 是别名）
readyagents runs report RUN_ID	运行的本地 HTML 摘要
readyagents runs replay RUN_ID	根据已存储的输入创建新运行
readyagents runs delete RUN_ID --yes	删除一条本地运行记录
readyagents runs gc --yes	清理成功/失败/已取消的运行（保留暂停的运行；拒绝删除保留期限内的记录，除非使用 --override-retention）
readyagents runs fork / diff / freeze / migrate	时间机器：派生运行、对比两个运行、冻结 cassette、将 JSON 迁移到 SQLite
readyagents connectors list / show / test	小型受治理目录（rest、sql、object_storage、message、ingest）——并非 500 个 SaaS
readyagents sign / verify / lock / sbom / trust	供应链：签名证明来源，不代表安全
readyagents approvals serve	前台运行的 localhost 审批页面
readyagents studio [--port 8790] [--open] [--read-only]	前台运行的 localhost 画布和运行检查器
readyagents models list / show / route --explain	仅供查看的模型目录和路由说明（不调用服务提供商）
readyagents mcp serve	Stdio MCP 服务（内置工具）；--json 会输出协议版本
readyagents mcp probe URL	只读的 server/discover 诊断（绝不调用工具）
readyagents a2a serve PATH	为一个工作流前台运行的 A2A 入口（默认使用 loopback）
readyagents a2a card PATH	确定性的 Agent Card（不使用网络）
readyagents a2a probe URL	只读的远程卡片诊断（不显示机密值）
readyagents memory list / show / search / forget / export	本地限定范围的记忆（除可选嵌入外均可离线使用）
readyagents knowledge ...	导入、同步、引用和遗忘知识文档（仅前台运行）
readyagents table ...	检查中间表：head、schema、stats
readyagents triggers ...	检查已声明的触发器、试运行映射、列出事件（不会启动监听器）
readyagents skills ...	安装、列出、导出和移除 Agent Skills（开放格式；没有市场）
readyagents agents-md	输出项目上下文：如何在此处运行、验证和测试工作流
readyagents package ...	构建、安装和编目工作流包（安装前审查）
readyagents health	按指纹对运行存储中的故障分组（无守护进程，无遥测）
readyagents bench ...	默认离线的基准测试套件，标注引擎耗时与实时耗时
readyagents sessions ...	列出、显示、关闭、重放和冻结对话会话（每轮对话都是一次运行）
readyagents serve ...	前台运行的 loopback 界面（随进程停止）
readyagents packs [--pack PATH]	列出已安装的 / 本地 pack
readyagents doctor	只读的平台 / extras / 权限 / loopback / 运行存储 / 主权诊断
readyagents version	输出版本

示例（除非另有说明，否则无需密钥）

文件	展示内容
examples/calc_pipeline.yaml	内置工具、转换、条件
examples/calc_pipeline.json	与 calc_pipeline.yaml 相同的图
examples/approval_gate.yaml	人工审核暂停／恢复
examples/ollama_local.yaml	无需密钥的环回 OpenAI 兼容路径（不调用在线模型）
examples/quorum_gate.yaml	双审核人审核关卡（无需密钥）
examples/expiring_gate.yaml	延迟截止时间，on_expire: reject（无需密钥）
examples/multi_gate.yaml	两个顺序执行的审核关卡
examples/fanout_gate.yaml	并行分支 + 审核
examples/include_demo.yaml	子工作流 include（new --from-example）
examples/composed_gate.yaml	Include + 并行 + 审核（new --from-example）
examples/research_brief.yaml	Agent 节点（需要密钥）
examples/support_triage.yaml	分类后分支（需要密钥）
examples/code_review.yaml	read_file + 审查（需要密钥）
examples/agent_tools.yaml	Agent tools: [calc]（需要密钥；--dry-run 无需密钥）
examples/foreach_calc.yaml	顺序 foreach + calc（无需密钥）
examples/policy_gated.yaml	针对受污染 write_file 的策略关卡（无需密钥）
examples/readyagents.policy.yaml	入门防火墙策略
examples/json_mutate.yaml	json_set / json_merge（无需密钥）
examples/table_pipeline.yaml	type: table + type: classify（验证时无需密钥）
examples/list_dir.yaml	内置 list_dir（无需密钥、MCP 或 Node）
examples/eval/pass.yaml	无需密钥的 readyagents eval 测试套件
examples/a2a_delegate.yaml	type: a2a 试运行（不访问网络）
examples/memory_triage.yaml	type: memory 先写入再搜索（无需密钥）
examples/code_reshape.yaml	type: code JSON 输入／输出（无需密钥，子进程）
examples/batch_echo.yaml	无需密钥的 readyagents batch 行回显（batch_rows.jsonl / .csv）
examples/connector_rest.yaml	无需密钥的 rest 连接器，针对本地测试样例运行
examples/connector_demo.yaml	本地 --pack 连接器（examples/packs/connector_pack.py）
examples/gated_write.yaml	审核后执行 write_file（无需密钥）
examples/env/echo.yaml	无需密钥的环境部署 + run --env（examples/env/readyagents.env.yaml）

文档

• 为什么选择 ReadyAgents？
• 入门指南
• 前十分钟
• 概念
• 配置（BYOK）
• 工作流
• 编写（JSON Schema、编辑器、带位置的错误）
• 连接器（小型目录；默认对写入类操作进行门控）
• 主权模式（进程内拒绝出站流量，并非 OS 沙箱）
• 成本 / TokenOps（仅供参考，不等同于服务提供商账单）
• 时间机器（记录 / 回放 / 分叉 / 比较 / 冻结）
• MCP · MCP 粘贴目录
• A2A（不可信的远程内容；委托可能导致数据外泄；不构成认证）
• 记忆（不可信；可能导致延迟注入和范围逃逸）
• 规模与批处理（选择启用的前台批处理；基准测试会标明引擎与实时运行）
• 流式传输（选择启用 --stream；不支持音频）
• 护栏 / 输出契约（选择启用 contract:；已声明的规则）
• 多 Agent 团队（选择启用 type: team；成员固定；不对质量作保证）
• 模型路由（选择启用 routing:；已声明的策略）
• 多模态 I/O（选择启用 MediaPart / type: document / type: transcribe；额外功能；不保证 OCR 能力）
• 知识管道（选择启用 type: ingest；引用 / 时效性）
• 数据管道（选择启用 type: table / type: classify）
• 长时等待（选择启用 type: wait；惰性 wake）
• 事件触发器（选择启用 triggers:；核心中不包含监听器；至少一次投递并需保证幂等性）
• Agent Skills（选择启用 type: skill；开放格式）
• 受治理的浏览器使用（选择启用 type: browser；已声明的操作；不处理 CAPTCHA；可选扩展包）
• 对话会话（选择启用 type: converse；回环 serve chat；核心中不支持音频）
• 环境与发布（选择启用 readyagents.env.yaml；固定版本；门控晋级）
• 迁移（选择启用 readyagents import；仅进行结构转换）
• Agent 注册表（选择启用 readyagents registry；已声明的根目录；Annex VIII 草案导出）
• 蒸馏（选择启用 readyagents distill；训练由扩展包负责；适配器须通过留出集门控）
• 打包（选择启用 readyagents package；先审查再安装）
• 模拟（选择启用 readyagents simulate；由声明驱动的用例）
• 自我修复（选择启用 readyagents health / recovery:；指纹和故障安全门控）
• 基准测试（选择启用 readyagents bench；离线录制数据）
• 扩展包
• 供应链信任（签名证明来源，不证明安全性）
• 持续交付扩展包（可选，单独分发）
• 平台支持
• CLI
• 合规证据（第 12–14 条映射；不构成认证）
• 可观测性
• 变更日志
• 2.0.12 版发行说明

安装可选依赖

LLM 和 MCP 可选依赖并非必需。

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]"

从克隆的仓库安装时，可使用 pip install -e ".[openai]" 安装相同的可选依赖（也可选择 anthropic / gemini / bedrock / vertex / mcp / all）。可选的 [otel] 依赖不包含在 [all] 中；它不会启动任何收集器（见 observability.md）。可选的 [sign] 依赖（Ed25519 工件签名）、[jwt]、[gemini]、[bedrock]、[vertex]、[image]、 [pdf]、[audio] 和 [table] 依赖也不包含在 [all] 中。默认的未签名运行绝不会导入这些依赖。编解码器作为可选依赖提供；核心安装仅支持文本。表格操作可选用 Pandas；使用标准库即可满足需求。

然后运行 cp .env.example .env，并粘贴你自己的密钥。仅使用内置工具的核心工作流不需要可选依赖、密钥或 Node.js。

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

本仓库不包含的内容

常驻运行套件需加入候补名单，且不出售。

常驻运行 / 持续运行的工作进程不属于 Core。可选的 readyagents-pack-continuous 发行包（独立仓库，不是 Core 可选依赖）可以通过明确的前台命令运行已配置的工作流。安装 Core 不会启动任何调度器或监听器。

托管控制平面。托管式恢复和远程运行存储。SSO、多租户团队、计费。

Core 支持在本地单次运行中持久化、恢复和暂停以进行审批，但不支持常驻运行。

许可证

Apache License 2.0。详见 LICENSE。

安全

请按照 SECURITY.md 中的说明报告漏洞。公开联系邮箱：[email protected]。请勿提交 API 密钥。本地操作员文件（例如 .env）已加入 git 忽略列表。