Shepherd: Open-Source Python Substrate for Agent Run Management

Researchers from Northeastern University and Stanford University have introduced Shepherd, an open-source Python runtime substrate designed to manage long-running AI agent executions. This new substrate records agent runs as a Git-like trace of typed events, allowing any past state to be forked and replayed. This capability addresses a significant challenge with current agent systems where accumulating state, such as edited files, running development servers, installed packages, and prompt caches, is not effectively captured or recoverable. When an agent makes an error, such as misinterpreting a traceback and incorrectly modifying a file, existing recovery methods are costly. Patching forward increases context and token expenses, while restarting from the beginning requires re-executing all model and tool calls and cannot guarantee exact reproducibility due to the non-deterministic nature of agent runs. Shepherd aims to provide the desired functionality of jumping back to a specific earlier state, a feature not offered by current runtimes, which typically only version files, not live processes or caches. The research team reports that Shepherd achieves forks that are 5 times faster than Docker and maintains over 95% prompt-cache reuse during replay. Shepherd is available under the MIT license and can be installed via pip as 'shepherd-ai', requiring Python 3.11 or later. Operating system-level permission enforcement is supported on macOS using Seatbelt and on Linux through Landlock within a privileged container. The potential industries that can benefit from Shepherd include software engineering and DevOps, AI infrastructure and agent platform vendors, quantitative finance research, security tooling and offensive-security research, and data engineering. The common characteristic across these fields is the need for managing long-horizon agent runs with substantial sandbox state, where the cost of redoing a failed run is significant. Specific applications envisioned for Shepherd include live supervision of coding agents, enabling a meta-agent to revert detrimental changes before they are committed. It also facilitates automated recovery from incorrect tool calls without necessitating a full restart of the agent. Furthermore, Shepherd can be used for branching exploration of candidate agent strategies, allowing for side-by-side comparisons, and for generating rollouts in reinforcement learning by forking at selected turns. Shepherd fundamentally changes how agent runs are managed by providing a robust, version-controlled approach to state management, inspired by the principles of version control systems like Git.