Repo-lab
AIツール

Shepherdとは？Gitライクな可逆トレースでAIエージェントを安全に管理するPythonフレームワーク

⭐ 1,493 stars GitHub →

Shepherdとは？Gitライクな可逆トレースでAIエージェントを安全に管理するPythonフレームワーク

ShepherdはAIエージェントの実行を可逆的なGitライクトレースとして記録するPythonランタイム基盤です。エージェントの変更はファイルに直接反映されず「レビュー可能なプロポーザル」として保持され、承認後に適用されます。macOS・Linuxでのサンドボックス実行・マルチ候補の並列レビュー・ロールバックに対応しています。

GitHubで急上昇中の shepherd-agents/shepherd をご紹介します。 スター数 1493★ を獲得し、AI・LLMエージェントフレームワーク分野で注目されています。

Shepherdとは？AIエージェント実行を「可逆的トレース」で管理するフレームワーク

Shepherd は、AIエージェントの実行を検査可能・可逆的・監督可能にするためのPythonランタイム基盤です。エージェントが実行した全ての操作はGitのコミットのような 「実行トレース」 として記録され、いつでもロールバックできます。

最大の特徴は 「レビュー可能なプロポーザル」モデル です。AIエージェントが何らかのファイル変更を提案しても、それはすぐにワークスペースへ反映されません。人間がレビューして select（選択）・apply（適用）・release（公開）・discard（破棄）のいずれかを選んで初めて変更が確定します。

2026年7月に v0.3.0 がリリースされ、複数候補の並列実行結果を三方向マージで適用できる apply 動詞が追加されました。論文（arxiv: 2605.10913）と連動した研究プロジェクトでもあり、4名のコントリビューターが活発に開発を続けています。

こんな人におすすめ:

  • エンジニア向け: AIコーディングエージェントをプロダクションで安全に使いたいPythonエンジニア・AIエンジニアに最適。エージェントの出力を監査・ロールバックできる仕組みが必要なチームに強く推奨
  • 非エンジニア向け: プログラミング知識が必要なAIエンジニア・MLエンジニア向けの高度なエージェント管理フレームワークです

Shepherd 使い方：インストールからクイックスタートまで

インストール

pip install shepherd-ai

Python 3.11+ が必要です。macOS または Linux（Ubuntu等）で動作します。Windows は未対応（WSL 使用を推奨）。

Claude CLI の準備

Shepherd はデフォルトで Claude CLI を介してエージェントを実行します。事前に Claude サブスクリプションまたは ANTHROPIC_API_KEY を設定してください。

# 長期トークンを設定（サブスクリプション利用者向け・推奨）
export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)

ワークスペースの初期化と動作確認

mkdir /tmp/agent-task && cd /tmp/agent-task
shepherd init             # Shepherd ワークスペースとして初期化
shepherd doctor claude    # Claude CLI・認証・サンドボックスの動作確認

タスクの定義とエージェント実行

Shepherd におけるタスクは 本体を持たないPython関数 として定義します。関数のシグネチャとdocstringがエージェントへの指示と権限付与を兼ねています。

import shepherd as sp

def write_program(
    repo: sp.GitRepo,      # ← GitRepo型のパラメータが書き込み権限を付与する
    prompt: str,
    output_path: str = "program.py",
) -> None:
    """Write a small, self-contained Python program that does what `prompt` asks.

    Save it to output_path. It must run with plain `python3`, read no input,
    and finish on its own within about ten seconds.
    """
    # ← 本体なし。エージェントがdocstringを読んで実装する

shepherd demo write agent-task > agent_task.py
python agent_task.py
# → エージェントがプログラムを書くが、直接反映されない
# → 「retained output」としてプロポーザルが保持される

Shepherd 使い方：4つの settlement 動詞でプロポーザルを操作する

select・apply・release・discard

エージェントが生成した変更（プロポーザル）は4つの動詞で操作できます。

動詞 動作
select Fast-forward 形式で変更を適用（ワークスペースが変化していない前提）
apply 三方向マージで変更を適用（ワークスペースが移動していても可・v0.3.0で追加）
release 変更を公開・他のエージェントから参照可能にする
discard プロポーザルを破棄（変更を採用しない）

apply はパスが重複しない変更セット同士は自動マージしますが、重複する場合はフェイルクローズ（安全側に失敗）します。AIエージェントの出力をN件並列生成して、最良のものを選んで適用するワークフローが可能です。

パーミッションモデル：シグネチャがパーミッションサーフェス

型ヒントで権限を宣言

Shepherd の権限モデルはユニークです。関数のパラメータ型が そのままエージェントへの権限付与 になります。

def risky_task(
    repo: sp.GitRepo,      # GitRepoへの書き込み権限
    web: sp.WebAccess,     # Web アクセス権限
    prompt: str,
) -> None:
    """...docstring..."""

sp.GitRepo 型のパラメータがあるとき、エージェントはそのリポジトリへ書き込めます。sp.WebAccess があればネットアクセスが許可されます。パラメータから型を外せばその権限が消えます。コードレビューでパーミッションが読める という設計は、大規模チームでのガバナンスに有効です。

LangChain・AutoGen との違い・なぜ今 Shepherd が注目されるか

既存フレームワークとの差別化

LangChain や AutoGen、OpenAI Agents SDK などの既存エージェントフレームワークは、エージェントの実行を「トランスクリプト」と「環境スナップショット」として扱います。エージェントが誤ったファイル変更を行った場合、手動でのロールバックが必要になります。

Shepherd の差別化ポイントは3つです：

  1. 可逆実行トレース: Dockerコミットより約5倍高速なcopy-on-writeフォークと95%KVキャッシュ再利用により、状態のブランチ・ロールバック・リプレイが実用的なコストで行えます
  2. プロポーザルモデル: エージェントの変更が直接ファイルシステムに書き込まれない設計により、人間による品質ゲートが必須の企業環境でも採用しやすい
  3. メタエージェント対応: エージェントを管理するエージェント（メタエージェント）がトレースを読み取り、実行中のエージェントをリダイレクト・修正できる

2026年7月に急速にスターを集めたのは、AIコーディングエージェント（Claude Code等）の普及に伴い「安全にエージェントを使う仕組み」への需要が急増しているタイミングと重なったためです。

こんな人に向いている：Shepherd Python AIエージェント フレームワーク 活用シーン

AIエンジニア・MLエンジニア

Claude等のコーディングエージェントをプロダクションコードベースに適用する際、変更をすべてレビューしてから適用するワークフローをShepherdで構築できます。誤ったコード変更を「discard」するだけでロールバックが完了するため、本番コードへの誤適用リスクを大幅に低減できます。

ソフトウェアエンジニア・チームリード

複数のAIエージェントに同じタスクを並列実行させ、生成された複数のプロポーザルを比較・最良案を選択するワークフローに活用できます。N件の候補を同時生成してベストを apply するアプローチは、AIエージェントの出力品質のばらつきを人間がコントロールする効果的な手法です。

セキュリティ・コンプライアンス担当

Shepherd のパーミッションモデルは関数シグネチャに明示されるため、AIエージェントが持つ権限をコードレビューで監査できます。エージェントへの権限付与を型ヒントで管理するアプローチは、SOC2等のコンプライアンス要件でのログ・監査要件を満たすための出発点になります。

使う前に知っておきたいこと

Alpha 版・API 変更の可能性

Shepherd は現在 Alpha 版（v0.3.0） です。リリース間でAPIが変更される可能性があります。プロダクション利用前にバージョンを固定（pip install shepherd-ai==0.3.0）することを推奨します。

Windows は未対応（WSL を使用）

macOS（Seatbelt）と Linux（Landlock）でのみOSレベルのサンドボックス実行が有効です。Windowsではサンドボックス実行が形式的（advisory-only）になるため未サポートです。WSL 2経由での利用を推奨します。

Python 3.11+ 必須

Python 3.10 以下では動作しません。pyenv や uv で Python 3.11+ 環境を準備してください。

Claude CLI または Anthropic API キーが必要

エージェント実行にはAnthropicのClaudeが必要です。Claude サブスクリプションまたは ANTHROPIC_API_KEY を事前に準備してください。shepherd doctor claude で環境確認できます。

ライセンス

Shepherd はApache 2.0ライセンスで公開されており、商用利用・改変・再配布が可能です。著作権表示とLICENSEファイルの保持が必要です。

関連ツール・おすすめサービス

  • Perplexity AI — Shepherd と組み合わせてAIエージェントの調査・情報収集タスクを強化。AIファクトチェックにも活用できる
  • DigitalOcean — App PlatformやDropletでShepherdのLinuxサンドボックス環境をクラウドに構築。安全なリモートエージェント実行基盤として利用可能

この技術を学ぶ

AIエージェント・LLMフレームワークに興味を持った方には、Udemyのオンラインコースもおすすめです。

まとめ

Shepherdは「AIエージェントの変更をレビューしてから適用する」という新しいパラダイムを実現するPythonフレームワークです。可逆実行トレース・プロポーザルモデル・関数シグネチャベースのパーミッション管理により、AIコーディングエージェントを企業環境で安全に活用するための理想的な基盤となります。AIエンジニア・MLエンジニア・チームリードに特に強く推奨します。

GitHub でチェックする →

毎日更新のGitHubツール情報

LINEで受け取って最新情報をキャッチアップしよう

友達追加する（無料）

関連記事

この記事が役に立ったらシェアしてください