Program meta-agents in Python¶

Write agents as simple typed functions, and meta-agents as functions that take your agents as input.

hello.py

import shepherd as shp
from shepherd.providers import claude


@shp.task
def implement(repo: str, feature: str) -> str:
    """Implement the feature in the repo and report what changed."""


@shp.task
def oversee(worker, repo: str, feature: str) -> str:
    """Run the worker on the feature. If its tests fail, revert and retry, then report."""


with shp.workspace(model=claude("sonnet-4-5")):
    print(oversee(implement, repo=".", feature="login"))

Find your path¶

Build your first agent

A typed task, a workspace, and a small working reviewer. Offline and deterministic.

First Shepherd app
Debug and test a run

Read typed failures, keep runs deterministic, and test model-backed code without live calls.

Debug your first run
Understand & evaluate

The mental model behind tasks, effects, and runs, plus a record of what these docs can claim today.

Concepts: Tasks

Why Shepherd¶

Typed. A task is a function with a signature and a docstring. The return type is the contract the model must satisfy.
Observable. Every run records what was sent and returned, so you debug by reading a trace instead of guessing.
Composable. Tasks are values. Pass them, supervise them, and build bigger programs out of small ones.

Shepherd v1.0-dev (prototype docs)

This site is built scaffold-first: a page goes public only when its content is backed by checked source. Everything else stays in the reviewer build. The source-state inventory records what these docs can claim today.