shepherd

像 Git 一样分叉回滚 Agent 运行，重放省 95% 算力

Shepherd 是一个面向智能体（Agent）的运行时底座，把每次执行过程记录成可逆的、类似 Git 的轨迹，让元智能体（meta-agent）能够观察、分叉、重放和回滚任意一次运行。它解决的核心问题是：当前 Agent 执行过程不可回溯、难以调试和优化，一旦出错只能从头再来，训练和调优成本极高。Shepherd 通过写时复制（copy-on-write）机制把 Agent 与环境耦合在一起进行分叉，速度比 docker commit 快约 5 倍，重放时 KV-cache 复用率约 95%，大幅降低重复计算开销。它专为元智能体设计，可用于监督、优化和训练其他 Agent，支持 MCTS-RL、树状 RL、工作流自动化等场景，让 Agent 的试错、分支探索和回滚变得像操作 Git 分支一样自然。

开源 unknown 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 2417

维护状态较活跃

是否开源是

定价模式 unknown

项目数据

分类智能体

开发团队shepherd-agents

所属国家

官网地址https://shepherd-agents.ai

GitHubhttps://github.com/shepherd-agents/shepherd

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型mcts-rl,meta-agents,meta-optimization,runtime-supervision,tree-rl,workflow-automation

GitHub 星标★ 2417

30天Star增速

HF 下载量

上线时间2026-06-24 00:00:00

最近更新2026-09-16 00:00:00

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-14

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

Python 3.11 或更高版本
macOS 或 Linux（Windows 不支持，需使用 WSL）
使用 agent 快速上手需安装并登录 claude CLI，或提供 ANTHROPIC_API_KEY
Linux 上的授权强制执行需要特权容器（Landlock）

安装与启动步骤

1安装 Shepherd

用 pip 从 PyPI 安装 shepherd-ai 包，建议装在虚拟环境中避免污染全局。
```
pip install shepherd-ai
```
2初始化工作区

新建一个临时目录并执行 shepherd init，把它变成一个 Shepherd 工作区。
```
mkdir /tmp/agent-task && cd /tmp/agent-task
shepherd init
```
3检查 claude 环境

确认 claude CLI、登录凭证和沙箱是否就绪；加 --probe 可做一次真实认证往返。
```
shepherd doctor claude
```
4生成示例任务

把官方 demo 的 agent 任务脚本写到当前目录的 agent_task.py 文件中。
```
shepherd demo write agent-task > agent_task.py
```
5运行 agent 任务

执行脚本，agent 会工作约一分钟；产物不会写入你的目录，而是成为保留输出。
```
python agent_task.py
```
6查看保留输出

不应用任何变更，直接读取最新 changeset 中的 donut.py 并交给 python3 执行。
```
shepherd run changeset --latest --read donut.py | python3 -
```
7查看完整记录

用 show 查看这次运行的完整记录，加 --json 可拿到机器可读的持久化数据。
```
shepherd run show --latest
```
8保留或丢弃结果

满意就用 select 保留、apply 合并，不满意用 discard 丢弃，轨迹都会记住。
```
shepherd run list
```

关键配置

配置项	必填	说明	示例
`ANTHROPIC_API_KEY`	否	使用 Claude agent 时提供的 API 密钥，与订阅登录二选一	`sk-xxxxxxxx`
`CLAUDE_CODE_OAUTH_TOKEN`	否	长期令牌，订阅账号在沙箱中运行更稳定	`export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)`

如何确认成功

执行 shepherd run list 能看到本次运行及其状态，shepherd run changeset --latest 能列出保留输出即可。

常见问题

Q：没有 API key 能跑起来吗？

A：可以。README 提供了离线快速上手，使用确定性的 provider，无需任何密钥即可走通保留输出流程。

Q：Windows 上可以安装吗？

A：不支持。授权强制执行仅在 macOS（Seatbelt）和 Linux（Landlock，特权容器）实现，Windows 上请改用 WSL。

Q：Claude 返回 HTTP 403 组织策略错误怎么办？

A：这是账号或组织层面的限制，不是登录问题。换一个密钥或联系组织管理员解决。

Q：claude CLI 直接卡住不返回？

A：例如版本过期会导致挂起，最终表现为 budget 超时而不是认证错误，请更新 claude CLI 版本。

Q：订阅登录在沙箱里失败怎么办？

A：短时有效的登录会话无法在沙箱内刷新，建议用 claude setup-token 生成长期令牌后再运行。

注意事项

Shepherd 处于 early alpha，API 可能随版本变化，请关注官方文档更新。
agent 的产物默认是 retained output，不会直接改动你的文件，需显式 select 或 apply 才生效。
自己开发 Shepherd 时改为本地可编辑安装：python -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt。
更多后端选择和完整 run 命令面见官方文档 https://docs.shepherd-agents.ai/。

核心亮点

写时复制分叉比 docker commit 快约 5 倍，重放 KV-cache 复用率约 95%，显著降低试错成本
把 Agent 执行抽象为可逆的 Git 式轨迹，支持观察、分叉、重放、回滚，调试和优化体验直观
专为元智能体设计，天然适配 MCTS-RL、树状 RL 等需要大量分支探索的训练范式

不足之处

项目较新、社区规模有限，长期维护和生态集成情况待观察
写时复制与 KV-cache 复用对底层运行时和模型服务有较强假设，接入自有环境可能需额外适配

适用场景

元智能体监督和优化子智能体，通过分叉对比不同策略效果
Agent 强化学习训练中做树状搜索和 MCTS 分支回放
复杂工作流调试时回滚到任意历史步骤，避免从头重跑

替代项目

LangGraph、AutoGen、DSPy

项目介绍

shepherd 是一个智能体领域的开源项目，官方简介：A runtime substrate that turns an agent's execution into a reversible, Git-like trace, so meta-agents can observe, fork, replay, and revert any run. Couples agent and environments in a copy-on-write fork ~5x faster than docker commit, with ~95% KV-cache reuse on replay. Framework built for meta-agents to supervise, optimize, and train other agents。项目使用 Python 开发，在 GitHub 上获得 2409 星标。

上一篇：datagouv-mcp

下一篇：agentflow