Live demo · Downloadable sourceProduct · Extends the The Agent Harness field note

Agent Harness Starter Kit

A real, tested, downloadable reference implementation of tool contracts, a step/cost budget, an approval gate, and structured tracing — the four guardrails from the the-agent-harness field note, with an AI agent narrating a real captured execution trace.

Real, tested code you can run and download — the trace below is genuine, not written by hand

Unlike the other products here, the core artifact is not an AI call — it's a small, dependency-free Python package (contracts, budget, approval gate, tracer) with 19 passing unit tests, downloadable in full below. Clicking “Run the demo” executes that real code on the server and returns its actual captured trace — the same trace is pinned by a test, so it can never silently drift from what's shown here. Only the plain-language walkthrough underneath the trace is AI-generated, and it is instructed to narrate the given trace, not invent a different one.

How it works

Four small guardrails, each independently testable:

@dataclass(frozen=True)
class ToolContract:
    """Describes one callable tool: its name, a human-readable description,
    the JSON-schema-like shape of its arguments, an estimated cost per call,
    and whether calling it requires human approval before it runs.
    """
    name: str
    description: str
    parameters_schema: dict[str, Any]
    fn: ToolFunction
    estimated_cost: float = 1.0
    requires_approval: bool = False

def check(self, additional_cost: float) -> None:
    if self.steps_used + 1 > self.max_steps:
        raise BudgetExceededError(
            f"step budget exceeded: {self.steps_used + 1} > {self.max_steps} max steps"
        )
    if self.cost_used + additional_cost > self.max_cost:
        raise BudgetExceededError(
            f"cost budget exceeded: {self.cost_used + additional_cost:.2f} > "
            f"{self.max_cost:.2f} max cost"
        )

@dataclass
class ApprovalGate:
    """approver receives (tool_name, args) and returns True to approve or
    False to deny. The default approver denies everything, so a gate
    nobody configured fails closed rather than open."""
    approver: Callable[[str, dict], bool] = field(default=_deny_everything)
    decisions: list[dict] = field(default_factory=list)

    def review(self, tool_name: str, args: dict) -> bool:
        approved = self.approver(tool_name, args)
        self.decisions.append({"tool": tool_name, "args": args, "approved": approved})
        return approved

The demo scenario scripts a support-ops agent through three tools of differing risk (a free lookup, an approved discount, and a budget-limited refund), deliberately hitting every guardrail state — a normal call, a malformed call, an approved call, a denied call, and a call that exhausts the budget — in one run.

Try it

Loading the real captured trace…

Download the starter kit (.zip) ↓ — real source, tests included, no external dependencies.

Why this exists

This is a direct, runnable companion to the-agent-harness field note ↗: rather than only describe why contracts, budgets, approval gates, and tracing matter for production agents, this ships the smallest version of each that still genuinely works, with tests proving it, so the ideas in that post can be read, run, and adapted rather than taken on faith.

Production checklist

Zero external dependencies — pure standard-library Python, easy to read end to end.
19 passing unit tests, including a pinned test on the exact demo trace shown here.
The download is generated at build time from the real source, never a stale hand-made copy.
The 'Run the demo' button executes the real code server-side, not a canned fixture.
The narrator agent only explains the given trace; it cannot alter or invent a step.