代理框架與可重現性
Shepherd v0.3.0 Retains Agent Changes as Reviewable Proposals, but the Paper’s Automated Forking Supervision Is Not Yet Fully Delivered
Shepherd records model calls, tool operations, and file changes as persistent execution traces, allowing users to inspect or discard modifications before they enter the workspace. The latest documentation also explicitly states that the meta-agent delegation, in-flight forking, and automated retry interfaces demonstrated in the paper and on the project homepage are not yet directly usable features in v0.3.0.
Shepherd, which has recently attracted attention in the agent development community, aims to turn an agent run from an ephemeral conversation into a governable program object. The core capability actually delivered in v0.3.0 is retained execution: tasks are declared with the typed Python `@task` decorator, with read-only or read-write repository permissions encoded in the function signature. File changes produced during execution are retained alongside the workspace rather than directly overwriting the original files. Users can inspect the trace, changeset, and artifacts, then finalize the run with a one-time `select`, `apply`, `release`, or `discard` operation.
Its effect model records model requests, external tools, and filesystem boundary events, so auditing does not depend on text logs written by the agent itself. Linux uses Landlock and macOS uses Seatbelt for operating-system-level restrictions. The package requires Python 3.11 or later, while Windows users are currently advised to use WSL. This “isolate first, settle later” model is particularly useful for coding agents: even if a model generates suspicious changes, the working directory does not have to absorb the side effects first.
However, the project paper presents a more complete reversible execution model: a meta-agent can observe, intercept, roll back, and fork another agent. The research reports that forking is about five times faster than `docker commit`, replay can reuse more than 95% of the prompt cache, and dual-agent coding pass rates on CooperBench improve from 28.8% to 54.7%. Yet the v0.3.0 roadmap explicitly lists task-as-value delegation, persistent subagents, typed result projections, and automated supervised retries as features that have not yet been delivered. Evaluators should therefore base procurement or integration decisions on versioned documentation and executable examples, rather than treating the paper’s prototype results as representative of the full capabilities of the current PyPI package.