Playbooks AI

用英文 Markdown 编写 AI 代理行为,编译为语义指令集并由 LLM 像 CPU 一样执行。

Star 数
★ 94
最近更新
3 个月前
License
MIT
主语言
Python

30 秒速览

运行形态
命令行工具开发框架
可在哪里用
兼容但需适配Claude APIOpenAI API(部分支持)
费用
软件免费,模型调用费用自付
上手难度
低 · 几分钟可跑通
开始前需要
Python 3.12+Anthropic API 密钥pipShell / 命令行网络访问本地文件系统
典型场景
需要快速原型验证多步骤对话流程的 AI 开发者,直接写 Markdown 并 playbooks run 运行
不适合
  • 希望不引入外部 LLM 服务、完全本地可控的团队
  • 需要图形化流程编排器而非文本程序的人员
  • 不愿维护 Python 3.12 运行环境的小型团队
官网
runplaybooks.ai ↗ 来自 GitHub 仓库设置
维护状态
近半年有提交最近提交 2026-08-11最新版本 v0.7.4(2026-02-02)

这个 Agent 能做什么,适合哪些场景?

Playbooks 是一个语义编程系统:程序本身是 Markdown 文件(.pb),编译器把它转成语义指令集,运行时在 LLM 上执行,并保留真实的调用栈、断点调试和可验证的控制流。# 声明代理,## 声明 playbook,触发条件满足时 playbook 开始运行。自然语言步骤与 Python 代码可以互相调用,共享同一个调用栈和变量集合,例如英文 Main 调用 Python 的 process_countries,后者再逐个调用英文 GetCountryFact。当 playbook 返回时,其执行轨迹收敛为返回值,因此上下文不会无限增长。运行入口是 playbooks 命令行工具,另有浏览器 playground 和 VS Code 语言支持扩展用于断点调试。

读取 .pb Markdown 程序,由编译器解析出代理(#)、playbook(##)、触发器(如 ### Triggers 中的 At the beginning)与步骤列表;运行时按调用栈逐步执行,把一个英文步骤交给 LLM 解释并执行,同时可调用同一程序中内嵌的 Python 代码块(如用 @playbook 装饰的 async def process_countries)。Python 侧可用 await GetCountryFact(country)、await Say("user", ...) 调用自然语言 playbook 和输出消息。CLI 的 playbooks run 执行程序,-v 打印会话日志,--snoop=true 观察代理间消息,playbooks playground 启动浏览器界面查看运行日志。

  1. 需要快速原型验证多步骤对话流程的 AI 开发者,直接写 Markdown 并 playbooks run 运行
  2. 业务负责人希望阅读并审核实际执行的代理逻辑,而不是另一份会漂移的规格文档
  3. 需要把英文决策步骤与 Python 数据处理混编在一个程序里的团队,例如逐国调用模型再循环输出
  4. 想在 VS Code 中对自然语言步骤打断点、检查变量与调用栈的调试场景
  5. 需要事件触发、多代理协同等较大抽象而暂时不想自建编排图的工程团队

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • pip install playbooks
环境变量
ANTHROPIC_API_KEY
配置文件
.env .env.example
运行环境
Python 3.12+

如何安装或部署这个 Agent?

需要 Python 3.12+ 和一个 Anthropic API 密钥。用 pip 安装并导出密钥(也可写入 .env 文件,参考 .env.example 中的其他提供方):

pip install playbooks
export ANTHROPIC_API_KEY=your-anthropic-api-key

如何使用这个 Agent?

创建 hello.pb,用 # 声明代理、## 声明 playbook,并在触发器和步骤中写英文指令:

# Hello world
This is a hello world demo for the playbooks system

## Hello world demo
This playbooks demo prints a hello playbooks message

### Triggers
- At the beginning

### Steps
- Greet the user with a hello playbooks message
- Tell the user that this is a demo for the playbooks system
- Say goodbye to the user
- End program

运行程序并查看日志或代理间消息:

playbooks run hello.pb
playbooks run hello.pb -v
playbooks run hello.pb --snoop=true

启动浏览器 playground 查看执行日志:

playbooks playground

调试可在 VS Code 安装 “Playbooks Language Support” 扩展,打开 .pb 文件后在英文步骤上设置断点。

这个 Agent 有哪些优点和局限?

优点
  • 程序即 Markdown,业务方能直接阅读并指出逻辑错误,不需要单独的规格文档
  • 英文步骤与 Python 代码共享同一调用栈和变量,可互相调用(await GetCountryFact(...)、await Say(...))
  • 运行时提供真实调用栈、断点与变量检查,执行可验证而非依赖模型自觉遵守指令
  • playbook 返回时执行轨迹收敛为返回值,避免上下文无限增长
  • 官方给出与传统框架实现的对照:同一代理 29 行 vs 272 行
局限
  • 默认示例依赖 Anthropic API 密钥,需要外部付费模型服务与网络访问
  • 要求 Python 3.12+,对更早版本环境需要升级
  • 语义执行依赖模型质量,步骤解释结果随模型变化,非确定性高于纯代码
  • 未说明完整的离线或自托管模型路径;仅在 .env.example 中列出其他提供方
  • VS Code 调试需另行安装扩展,playground 为独立启动的进程

这个 Agent 与同类方案有什么区别?

README 明确与“传统代理框架”做了对照:同一国家事实代理在 Playbooks 中为 29 行 Markdown + Python,并链接到其传统框架实现为 272 行,指出后者需要编排图、状态机、重试逻辑和输出解析器;Playbooks 把这些交给运行时与 LLM 处理。文中未点名具体竞品框架。

与相关度最高的同类 agent 并排比较关键指标。

Agent 源码审查 形态 / 费用 Star 最近更新 主语言 完整支持的平台
Playbooks AI 当前 43 · 缺口较多 命令行工具免费 + 模型费 ★ 94 3 个月前 Python Claude API
LangChain 生成式 AI 实战 41 · 缺口较多 代码库 / SDK免费 + 模型费 ★ 1.5k 3 个月前 Jupyter Notebook OpenAI API · Claude API
OPC —— 一人公司 证据不足 Agent 插件 / 技能免费 + 模型费 ★ 199 18 天前 JavaScript Claude Code
Hello-Agents 智能体教程 53 · 缺口较多 网页应用免费 + 模型费 ★ 88k 8 天前 Python OpenAI API

FollowAgents 如何评估这个 Agent?

FollowAgents 源码审查 · FARS-2.1
缺口较多
43/ 100 五分制 2.2 / 5
信任安全 8/29
可靠稳定 8/14
适用触发 8/18
规范维护 9/18
有效结果 7/13
证据核验 3/8
查看各维度的扣分理由
信任安全8 / 29 · 1.4/5

证据显示这是一个在本地运行、由用户自带 ANTHROPIC_API_KEY 的框架,CLI 诊断输出到 stderr,调试服务器默认绑定 127.0.0.1,属于较克制的默认。但 debug/server.py 使用 eval() 执行断点条件与命中条件(虽限制 __builtins__),且框架会通过 litellm/langfuse/redis/fastmcp 向外部 LLM 与可观测服务发送数据,README 与 CLAUDE.md 均未说明数据流向、日志留存或敏感数据处理策略;无回滚/撤销机制描述;来源归属仅靠 README 徽章与 MIT 版权行,发布者身份未经验证。因此各项仅给 1,rollback 因完全无证据给 0。

可靠稳定8 / 14 · 2.9/5

main.py 与 cli.py 结构清晰,编译/加载/执行分层一致,pyproject 固定了依赖版本区间且 CI 有 lint 工作流,依赖可得性较好(2)。但失败信息方面仅有少量异常抛出(如重复 frontmatter 属性、多个 cli_entry),CLI 多处 except Exception 静默吞掉错误(load_public_json_from_program 直接 return None),错误可诊断性偏弱,给 1。

适用触发8 / 18 · 2.2/5

README 明确面向想用自然语言编排 agent 的开发者,给出 hello world、混合 Python/英文、VSCode 调试、playground 等场景,受众与场景覆盖充分(2)。但能力边界(哪些步骤 LLM 可自由发挥、哪些受编译约束、安全边界)只在 CLAUDE.md 中零散提及,缺少明确声明;触发精度依赖 LLM 语义判断,文档未说明歧义处理;环境适配仅声明 Python 3.12+ 与 Anthropic key,其他 provider 仅指向 .env.example,证据不足,均给 1。

规范维护9 / 18 · 2.5/5

README 信息架构完整(安装、运行、调试、文档、许可证、贡献),安装步骤具体可执行(2);示例丰富(2);LICENSE 为完整 MIT 文本(3)。但版本号仅出现在 pyproject(0.7.4),CHANGELOG 仅被引用未在包内呈现,版本化证据薄弱(1);命名稳定性方面 .pb/.pbasm/public.json 等概念在 README 与 CLAUDE.md 间存在表述差异,且 CLAUDE.md 末尾被截断(1);无已知限制/FAQ 章节(0);维护责任仅指向 CONTRIBUTING 与未验证的发布者,给 1。

有效结果7 / 13 · 2.7/5

README 的 hello world 与混合调用示例可直接复制运行,输出可用性较好(2);相较传统框架宣称 29 行对 272 行,边际价值主张清晰但对比链接为自建文档,未独立佐证(2)。成本收益方面,每次编译与执行都调用 LLM,且依赖 litellm/langfuse/redis 等较重栈,README 未讨论 token 成本、延迟或离线可用性,给 1。

证据核验3 / 8 · 1.9/5

README 的多数强主张(可验证执行、上下文折叠、272 行对比)指向外部文档而非仓库内可核对材料,claim_traceability 仅 1;CLAUDE.md 与 README 在架构描述上大体一致,但 CLAUDE.md 含“from git status”等易过时内容且被截断,交叉佐证有限(1);事实与推断分离方面,README 将“Software 3.0”愿景与具体实现混排,未明确区分已实现与路线图,给 1。

风险与缓解建议
  • 源码中未见:回滚或恢复路径运行前先备份,或在 git 分支、快照上操作,确保改动可以撤销。
  • 调试服务器使用 eval() 执行断点条件,虽限制内置函数,仍应视为潜在代码执行面,生产环境需谨慎启用。
  • 框架默认通过 litellm/langfuse/redis/fastmcp 与外部 LLM 及可观测服务通信,README 未说明数据流向、日志留存或敏感数据处理,使用前需自行评估数据外泄风险。
  • CLI 多处静默吞掉异常,出错时可能难以定位根因。
  • 发布者身份未经验证,维护责任与更新路径不明确;CLAUDE.md 内容含易过时的 git status 描述且被截断。
  • 缺少已知限制与成本/延迟说明,LLM 调用成本与离线可用性未评估。
证据充分度:低 评估于 2026年11月11日 审查版本 1f6ee0cc760f
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/playbooks.svg?lang=zh)](https://followagents.com/zh/agents/playbooks)
<a href="https://followagents.com/zh/agents/playbooks"><img src="https://followagents.com/badge/playbooks.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. v0.7.4
    发布说明摘录
    [v0.7.4] - 2026-02-01 Added Examples - Adaptive Waiting Example - Added example demonstrating adaptive waiting patterns for agents - Nativity Playbook - New nativity.pb example playbook Agent System - Unified Message Batching - Implemented unified RollingMessageCollector for batching all agent messages including direct and meeting broadcasts. Human messages now trigger immediate flush of pending batches for responsive interaction Performance …
    在 GitHub 查看 ↗
  2. v0.7.3
    发布说明摘录
    [v0.7.3] - 2025-12-19 Added Agent Communication - Progressive Timeout Notifications - Agents waiting for responses had no visibility into delays. Added wait mechanism with periodic timeout checks that collects interrupt messages from other sources (user, other agents) and returns combined notification. The LLM decides whether to continue waiting or take alternative action—no hard maximum wait time MCP Integration …
    在 GitHub 查看 ↗
  3. v0.7.2
    发布说明摘录
    [v0.7.2] - 2025-12-17 Added Telemetry & Observability - Event-Driven Langfuse Integration - Direct Langfuse calls created tight coupling between business logic and telemetry. Introduced comprehensive event handler system with LangfuseEventHandler class that subscribes to semantic business events and translates them to appropriate spans, observations, and traces …
    在 GitHub 查看 ↗

常见问题

运行是否需要付费?
软件本身是 MIT 许可的开源项目,但运行需要 LLM 提供方(README 快速上手使用 Anthropic API 密钥),费用按模型调用量由你自行承担。
自然语言步骤和 Python 如何协作?
同一 .pb 文件中可嵌入 Python 代码块,用 @playbook 装饰的函数可被英文步骤调用,Python 内也能 await 调用英文 playbook(如 GetCountryFact)并通过 Say 输出到用户,二者共享一个调用栈和变量。
执行结果可验证吗?
README 称运行时维护真实调用栈,支持逐步执行、断点、变量检查,-v 打印会话日志,--snoop=true 显示代理间消息;playbook 返回时执行轨迹收敛为返回值。
支持哪些模型提供方?
README 以 Anthropic API 密钥为例,并说明 .env.example 中列出了其他受支持的提供方,但未在正文逐项列出。
能不能在 IDE 里调试?
可以安装 “Playbooks Language Support” VS Code 扩展,在 .pb 文件的英文步骤上设置断点、查看调用栈和变量。
Playbooks AI 官网是什么?
Playbooks AI 的 GitHub 仓库填写的官网是 https://runplaybooks.ai。这个链接由仓库作者设置;源码在 GitHub(playbooks-ai/playbooks)。
Playbooks AI 开源吗?
开源。源码在 GitHub(playbooks-ai/playbooks),许可证是 MIT。
Playbooks AI 安全吗?
FollowAgents 的 FARS 评审(2026年11月11日)给 Playbooks AI 的“信任与安全”打了 8/29 分。评审没有在源码和文档里找到这些安全措施:回滚或恢复路径。接入真实账号或数据前:运行前先备份,或在 git 分支、快照上操作,确保改动可以撤销。
Playbooks AI 还在维护吗?
更新变慢了:GitHub 上最近一次提交是 2026-08-11,在最近半年内,但不在最近 30 天内。最新版本是 v0.7.4(2026-02-02)。
Playbooks AI 是谁开发的?
Playbooks AI 由 GitHub 账号 playbooks-ai 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念