shepherd: Supervise Agents with Reversible Execution Traces

Overview

Shepherd is a Python framework for running agent tasks in controlled workspaces and retaining their results as inspectable proposals. Instead of letting an agent’s changes immediately alter the working files, it records the run and lets a person or supervising system review, select, apply, or discard the output.

This approach is useful when agent work needs oversight or recovery: runs can be inspected and replayed, while repository access is expressed through task permissions. Shepherd is designed for developers building meta-agents and other systems that need to supervise, optimize, or train agents.

Key Features

• Records agent runs as durable, inspectable execution traces.
• Retains workspace changes as proposals that can be reviewed before applying.
• Supports selecting, applying, or discarding a run’s output.
• Offers replay and fork-oriented workflows for examining agent execution.
• Declares read-only or read-write repository access through task signatures and bindings.
• Enforces grants at the operating-system level on supported jailed devices.
• Provides a deterministic provider for trying the retained-output workflow without an API key.

Use Cases

• Agent framework developers: inspect and manage the effects of agents that edit code or other workspace files.
• Meta-agent researchers: build systems that supervise, compare, or optimize the execution of other agents.
• Teams reviewing generated changes: keep agent output separate from the working tree until a reviewer accepts it.
• Developers testing agent workflows: use deterministic runs to explore trace and proposal handling without configuring an external model provider.

Getting Started

Requires Python 3.11 or newer. Install the package with:

pip install shepherd-ai

See the README and documentation for setup, examples, and configuration details.

Alternatives

• bernstein: Bernstein governs agent workloads with declarative policies, approval gates, and isolation, while Shepherd focuses on inspectable, reversible traces and reviewable change proposals.
• agent-governance-toolkit: The toolkit adds policy enforcement, identity, and sandboxing around existing agents, while Shepherd records and replays agent work and stages changes as proposals.

Considerations

Shepherd is in early alpha, and its APIs may change. OS-level grant enforcement is supported on macOS and Linux, with Linux enforcement requiring a privileged container; Windows is unsupported, and the project recommends WSL. Using an external agent may require its CLI and credentials, though the deterministic provider supports an offline quickstart.