Using the Agent Workbench for Real Repository Tasks: A Complete Implementation Guide

The Agent Workbench is a minimal, three-file framework that enables autonomous AI agents to operate safely inside any Git repository by providing a declarative router, durable state storage, and a JSON task board.

The AI Engineering from Scratch repository (rohitg00/ai-engineering-from-scratch) teaches you to build every component of an AI system through hands-on lessons. Introduced in Phase 14, the Agent Workbench bridges the gap between curriculum exercises and production codebases, allowing you to deploy autonomous agents into real repositories with full version control and auditability. This guide shows you how to scaffold the workbench, run agent loops, and verify system health using the actual source files from the curriculum.

What Is the Agent Workbench?

The Agent Workbench is a version-controlled surface consisting of three core files that an autonomous agent can read, write, and verify without risking repository corruption. Unlike monolithic agent frameworks, this minimal design treats the agent as a stateful service that persists memory and task queues directly in the filesystem, making every operation reviewable via standard Git workflows.

Core Components

The workbench relies on three canonical files located in the .workbench/ directory:

• AGENTS.md – A declarative router that defines allowed actions and constraints. It serves as the single source of truth for the agent’s instruction set and security policies.
• agent_state.json – A durable JSON store that persists the agent’s memory, variables, and intermediate results across execution runs.
• task_board.json – A JSON task backlog that the agent reads to determine what to work on next, and writes to signal task completion or failure.

Schema Validation and Versioning

To prevent corruption, the workbench includes a schemas/ directory containing JSON-Schema definitions for the three core files. These schemas enable runtime validation of any write operation the agent attempts. Version tracking is handled via a .workbench-version marker file written by the installer, ensuring idempotent deployments and preventing accidental overwrites of existing state.

How to Scaffold the Workbench into Any Repository

The curriculum provides two methods for installing the workbench: direct scaffolding from source or installing a pre-built distribution pack.

Method 1: Direct Scaffolding with scaffold_workbench.py

The scripts/scaffold_workbench.py script generates the three core files and writes the installer. Run it from the curriculum root against your target repository:

python3 scripts/scaffold_workbench.py ./my-target-repo

This creates .workbench/AGENTS.md, .workbench/agent_state.json, and .workbench/task_board.json inside your target directory, along with the .workbench-version marker.

Method 2: Installing the Distribution Pack

If you have built the pack from the capstone lesson (phases/14-agent-engineering/42-agent-workbench-capstone/), use the included installer:

tar -xzf outputs/agent-workbench-pack.tar.gz -C /tmp/pack
/tmp/pack/agent-workbench-pack/bin/install.sh /path/to/your/repo

The installer at bin/install.sh checks the pack’s VERSION file against any existing .workbench-version and refuses to overwrite unless you supply the --force flag.

Running Autonomous Tasks with the Workbench

Once installed, the workbench provides a standardized interface for agent loops. Below is a complete implementation that reads the task board, executes commands, and persists state.

The Agent Loop Implementation

# my-agent.py

import json
import pathlib
import subprocess

WORKBENCH = pathlib.Path("./.workbench")
AGENTS_MD = WORKBENCH / "AGENTS.md"
STATE = json.load(open(WORKBENCH / "agent_state.json"))
BOARD = json.load(open(WORKBENCH / "task_board.json"))

def run_task(task):
    # Execute tool defined in AGENTS.md

    result = subprocess.check_output(["python3", "tools/execute.py", task["command"]])
    return result.decode()

for task in BOARD["tasks"]:
    if task["status"] == "todo":
        output = run_task(task)
        # Update state (validated by schema at write time)

        STATE["last_result"] = output
        task["status"] = "done"
        break

# Persist changes

json.dump(STATE, open(WORKBENCH / "agent_state.json", "w"), indent=2)
json.dump(BOARD, open(WORKBENCH / "task_board.json", "w"), indent=2)

Running python3 my-agent.py performs three operations: it loads the task board to find the next job, executes the job according to the constraints in AGENTS.md, and writes the result back to agent_state.json. Because these files are standard JSON, you can review every change using git diff .workbench/ and roll back if the agent produces incorrect results.

Verifying Workbench Health

The curriculum ships with a workbench audit skill that validates the seven critical surfaces of the installation. Invoke it via the SkillKit CLI:

skillkit run workbench-audit --repo /path/to/your/repo

The audit reports on the router (AGENTS.md), state file, task board, schemas, installer, version marker, and verification gates, identifying any missing or malformed components before you deploy an agent.

Summary

• The Agent Workbench consists of three files (AGENTS.md, agent_state.json, task_board.json) that provide a safe, version-controlled interface for autonomous agents.
• Use scripts/scaffold_workbench.py to generate a fresh workbench in any repository, or install a versioned pack via bin/install.sh.
• The workbench enforces JSON-Schema validation on all writes and tracks versions via .workbench-version to prevent state corruption.
• Run agent loops by reading task_board.json for work items and writing results to agent_state.json, with all changes visible in Git diffs.
• Validate installations using the workbench-audit skill to ensure all seven system surfaces are healthy before production use.

Frequently Asked Questions

What is the difference between scaffolding and using the distribution pack?

Scaffolding via scripts/scaffold_workbench.py generates the three core files directly from the curriculum source, ideal for development or customizing the router logic. The distribution pack (outputs/agent-workbench-pack/) is a versioned artifact created in the capstone lesson that includes the installer, schemas, and version markers, making it suitable for shipping to production repositories or sharing as a SkillKit skill.

How does the workbench prevent an agent from corrupting my repository?

The workbench isolates the agent’s write surface to three specific JSON files and one markdown file, all contained within the .workbench/ directory. The JSON-Schema definitions in schemas/ enforce structural constraints on every write. Additionally, AGENTS.md acts as a declarative policy layer that restricts which external tools the agent may invoke, creating a sandboxed execution environment.

Can I run multiple agents on the same repository using this workbench?

Yes, but you must coordinate access to agent_state.json and task_board.json. The curriculum recommends implementing a file-locking mechanism or using atomic writes (write to temp file, then rename) to prevent race conditions. Alternatively, you can instantiate multiple .workbench/ directories with unique names (e.g., .workbench-agent-1/) by modifying the scaffold script’s target path parameter.

Where can I find the complete source code for the workbench lessons?

The workbench implementation spans two lessons in Phase 14: Lesson 41 (phases/14-agent-engineering/41-workbench-for-real-repos/) covers the theory and scaffolding, while Lesson 42 (phases/14-agent-engineering/42-agent-workbench-capstone/) contains the pack assembly code in code/main.py. The top-level AGENTS.md in the repository root serves as the canonical reference for the router specification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}