Shepherd: Reversible Execution Traces for Programmable Meta-Agents

Summary

Shepherd is a Python runtime substrate designed for agent work requiring inspection, reversibility, and supervision. It records agent runs as durable, inspectable execution traces, enabling meta-agents to observe, fork, replay, and revert any operation. This framework couples agents and environments using a copy-on-write fork, offering significant performance benefits and robust permission enforcement.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

Shepherd is an innovative Python framework that provides a runtime substrate for agents, focusing on enabling programmable meta-agents through reversible execution traces. It transforms an agent's execution into a Git-like trace, allowing for deep inspection, replay, and reversion of any run. This capability is crucial for developing sophisticated meta-agents that can supervise, optimize, and train other agents effectively.

Why use and benefits

Shepherd offers several compelling advantages for agent development and supervision. Its core strength lies in turning agent execution into a reversible, inspectable trace, which is invaluable for debugging, auditing, and understanding agent behavior. The framework boasts impressive performance, coupling agents and environments in a copy-on-write fork that is approximately 5x faster than docker commit, with about 95% KV-cache reuse on replay. Furthermore, Shepherd provides robust security through OS-level grant enforcement for permissions, ensuring that agents operate within defined boundaries on macOS (Seatbelt) and Linux (Landlock). This makes it an ideal tool for building reliable and observable agent systems.

Installation

To get started with Shepherd, ensure you have Python 3.11+ installed. You can install the shepherd-ai package using pip:

pip install shepherd-ai

Examples

Shepherd provides a straightforward quickstart to demonstrate its capabilities. You can set up a workspace, run an agent task, and then inspect or apply its retained output. The framework allows agents to propose changes, which you can review and decide to keep or discard, without directly modifying your files until accepted. For a practical example, the write_program task demonstrates how an agent can generate code in a sandboxed environment. Offline quickstart options are also available, requiring no API keys. More detailed examples, including a citation-checker package and visual artifact notebooks, are available in the repository.