Single agent loop kit

A starter kit for moving a multi-agent system (a router or orchestrator in front of specialist subagents) toward one agent loop that loads skills and tools on demand. It is the companion to the article Building agents: When to fold subagents into your main agent loop.

Reference implementation. Not maintained and not accepting contributions.

The kit does not assume a single loop always wins. It measures. Every change is scored on the same eval before and after, and a subagent only goes away when the numbers say its replacement holds.

The idea

1. Measure. Find the evals you already have, fill the gaps, and score the system as it is today. If you have none, the kit builds one with you.
2. Combine. Merge the subagents that always run together.
3. Fold. Turn each remaining subagent into a skill and tools in the main agent, one at a time, and compare. Keep the ones that earn their own context, and call them as tools.

Then keep it healthy: one small team owns the system prompt and the shared eval, and each domain team owns its skills.

Try it in ten minutes

examples/support-desk is a small, runnable support agent with a router and six subagents, built so that each subagent has a known right answer. Follow examples/support-desk/RUNBOOK.md to watch Claude Code audit it, fold one subagent and print the before and after numbers.

Start with the free check. It needs no API key and spends nothing. From wherever you put the kit (downloaded as a zip, unzip it first):

cd single-agent-loop-kit/examples/support-desk
KIT_MODEL=fake python3 evals/run_eval.py --variant smoke

You should see nineteen lines ending in 19 tasks ran on the offline stand-in model, 0 harness errors. The plumbing works. The stand-in follows keyword rules, so that run is not scored. Scores come from the real run in the runbook.

Use it on your own system

1. Copy the skill into your agent repo:

   git clone https://github.com/anthropics/single-agent-loop-kit
   cp -r single-agent-loop-kit/skill <your repo>/.claude/skills/single-agent-loop

2. Open Claude Code in your agent repo and say: Run the single-agent-loop skill.

3. It audits first and stops to show you a verdict for each subagent: fold, merge, call as a tool, or keep. Correct anything it got wrong.

4. It then works the plan one change at a time. Each change gets its own eval run and a comparison, and you decide whether it stays.

It stops at the same points every time: after the audit, before any paid run, after the baseline, and after each change. Each stop is a short check-in with what it found, what it recommends and one question for you. Before a paid run, that includes a token estimate.

You do not need an eval to start. If you have none, or none that tests the whole system, it asks for a safe way to run your system on a test request and for some real requests, drafts about ten tasks, and has you correct what done means for each before it runs them.

The skill reads whatever orchestration code is in the repo, so it is not tied to a framework. It keeps its notes in single-loop/ in your repo.

What's in the box

It leans on tools you already have

The steps hand off to these Claude Code commands instead of rebuilding them:

The eval runner in the example writes the same results layout /claude-api build-eval uses, so /claude-api hillclimb and its report work on it directly.

When you don't need this kit

• You have no subagents yet. Start with one loop. Read reference_loop/loop.py and add tools and skills as testing shows you need them.
• Your subagents earn their context. Parallel research across fresh contexts, independent verification, or work that reads far more than the main agent needs afterwards are good reasons to keep a subagent. The audit will tell you so.
• Your system cannot be scored yet. Having no eval is fine: the baseline step builds one with you. But it needs two things only you can give. A way to run the system on a test request outside production, and someone who can say what a correct outcome is for the common requests. If either is missing, sort that out first. Without a score, a migration is a matter of opinion.

Cost

The audit reads code and costs what a Claude Code session costs. Eval runs call your model for every task, rep and version, so the skill asks before every paid run and gives a token estimate based on runs it has already measured. Start with ten tasks and two or three reps.

Tests

python3 -m unittest discover tests

They need no API key. They cover the scripts, the reference loop, and an offline run of both versions of the example.

What has run on a real model

Two runs of the example, by one person on one model, both recorded as they came out in examples/support-desk/example-run/: the audit, a twelve-task baseline and the returns fold, then a seventeen-task baseline and diagnostics called as a tool. Each write-up says what was removed from it after the run and what its run did not show.

Not run on a real model: the merge and upkeep steps, the finished single_loop/ version of the example, tasks t18 and t19, starting from a repo with no eval, and the kit on any system other than the example. The skill's wording also changed after the second run, and no session has followed the reworded steps yet.

Changed after both runs and checked offline only:

• The reference loop: a write gate is required when a tool writes, subagent tokens count against the budget, a batch of tool calls is capped, and an answer the verifier rejects twice is withheld.
• The skill loaders refuse two skills with one name and a skill that links out of the folder.
• The scripts escape names from their input before printing them, and compare.py stops on a grade that is not a number.
• The example: each task names the customer who is signed in, the runner checks task ids, a subagent's write needs a write gate, the router refuses a call it did not declare, and single_loop/ checks who owns a record.

Support

This project is provided AS IS. Issues and pull requests are not monitored, so we cannot guarantee fixes for bugs or implementation of feature requests. Fork it and adapt it to your own system.

License

Apache-2.0. See LICENSE.