Supervising Agents and Defining Agent Roles¶
Summary¶
This chapter covers how to supervise agents that act on your behalf: autonomy levels, logging, failure modes, runaway behavior, cost control, scheduling, and trust boundaries. It then defines the specialized roles in an agent team, such as planning, execution, reviewer, research, coding, and writing agents. After this chapter you can assign roles and decide how much autonomy each agent gets.
Concepts Covered¶
This chapter covers the following 23 concepts from the learning graph:
| Concept | Concept Impact Score |
|---|---|
| Agent Autonomy | 63 |
| Agent Supervision | 1 |
| Agent Logging | 4 |
| Agent Failure Modes | 5 |
| Runaway Agent | 1 |
| Cost Control | 5 |
| Task Scheduling | 47 |
| Background Tasks | 41 |
| Agent Evaluation | 1 |
| Agent Handoff | 31 |
| Context Isolation | 1 |
| Trust Boundary | 20 |
| Credential Handling | 10 |
| Planning Agent | 63 |
| Execution Agent | 53 |
| Planner Executor Pattern | 1 |
| Reviewer Agent | 49 |
| Research Agent | 1 |
| Coding Agent | 2 |
| Writing Agent | 9 |
| Analysis Agent | 1 |
| Literature Agent | 1 |
| Agent Roles | 34 |
Prerequisites¶
This chapter builds on concepts from:
- Chapter 1: Research Workflows and the Researcher as Orchestrator
- Chapter 2: How Language Models Work
- Chapter 3: Choosing Models and Writing Clear Prompts
- Chapter 4: Context Engineering and Advanced Prompting
- Chapter 6: Knowledge Bases, Personal Knowledge Graphs, and the Anatomy of an Agent Skill
- Chapter 8: Agents, Tool Use, and Subagents
A Flock Needs a Shepherd
One agent you can watch. Several agents, running while you work on something else, need rules you wrote in advance: how much each may do on its own, what it must log, and when it must stop. This chapter gives you those rules and the roles that make a team of agents legible. Trust, but verify!
Autonomy and Supervision¶
Agent autonomy is the degree to which an agent acts without a human decision at each step. It is a dial, not a switch, and the right setting is different for each task. An agent that may only suggest has no autonomy and no risk, and delivers a fraction of the benefit. An agent that acts unattended delivers the full benefit and carries the full risk. The art is to set the dial per task from the properties of the task and not from your confidence in the model.
Three properties of a task determine how far the dial can safely turn. Reversibility is whether the effect can be undone: an edit to a file in version control can, and an email that has been sent cannot. Reach is whether the result leaves your control, by being sent, published, or written to a shared system. Verifiability is whether you or a script can check the result quickly and objectively: a program that must pass tests is verifiable, and a paragraph of related work is not, without reading the cited papers.
A small ladder of levels makes the choice concrete. The levels are a convention of this book and not a standard.
| Level | Name | The agent may | Typical use |
|---|---|---|---|
| 0 | Suggest only | Propose; you perform the action | Anything that leaves your control and cannot be checked |
| 1 | Approve each step | Act after you approve each action | Irreversible or outward-bound actions that can be checked |
| 2 | Act within a boundary | Act freely inside a defined scope, and stop at gates for your approval | Reversible work whose quality needs a human read |
| 3 | Act and report | Act unattended and report afterwards | Reversible, local, automatically verifiable work |
Table 1. Autonomy levels and where each fits.
The assignment rule used in this chapter's exercise follows from the three properties. If the result leaves your control and cannot be verified, the agent suggests only. If it leaves your control and can be verified, each step needs approval. If it stays local but cannot be undone, each step needs approval. If it is local and reversible but cannot be checked quickly, the agent acts within a boundary and stops at gates. If it is local, reversible, and verifiable, it can act and report.
Agent supervision is the set of practices by which you keep a deployed agent honest while it works: watching what it does, bounding what it may do, sampling its output, and stopping it when it departs from the task. Supervision is not the same as reading everything. It is the design of where a human looks, so that attention goes where the risk is.
Autonomy Follows the Task, Not the Model
Notice what the three properties are about: the effect and not the agent. A very capable model should still not send email unreviewed, and a modest one can safely reformat a bibliography. Set autonomy by asking what the worst result of the action would cost and whether you could tell.
Diagram: Agent Autonomy Level Assigner¶
Agent Autonomy Level Assigner
Type: microsim
sim-id: agent-autonomy-level-assigner
Library: p5.js
Status: Built
Template: https://github.com/dmccreary/ai-persona-testing/tree/main/docs/sims/agent-autonomy-boundary
Bloom Level: Evaluate
Bloom Verb: recommend
Learning Objective: The learner will recommend an autonomy level from 0 to 3 for each of eight research tasks from its reversibility, reach, and verifiability, with at least 7 of 8 correct.
Prerequisites: agent autonomy, reversibility, reach, verifiability, and the four autonomy levels, all defined in the section "Autonomy and Supervision" above.
Evidence of Mastery: For each of eight tasks the learner commits one of four levels. A level is correct when it equals the level in Content, which follows from the assignment rule in Rules. Mastery is at least 7 of 8 correct on the first attempt. Reading the task attributes is exploration and is not evidence.
Misconceptions: (1) A capable model deserves more autonomy on every task. (2) Anything local is safe to run unattended. (3) If a result is outward-bound, a quick look at it is enough.
Instructional Rationale: Evaluate-level work needs the learner to apply criteria to cases and defend a choice. The attributes are given for each task, so the decision is about weighing them and not about guessing facts.
Content:
| # | Task | Reversible? | Leaves your control? | Verifiable quickly? | Correct level | Why (shown as feedback) |
|---|---|---|---|---|---|---|
| 1 | Reformat the entries of refs.bib to a venue's style | Yes, in version control | No | Yes, the document compiles and entries can be diffed | 3 | Local, reversible, and verifiable, so it can act and report. |
| 2 | Draft a related-work paragraph for your paper | Yes | No | No, claims need reading the cited papers | 2 | Local and reversible, but quality needs a human read, so it works within a boundary and stops at a gate. |
| 3 | Email a summary of the results to a collaborator | No | Yes | No | 0 | It leaves your control and cannot be checked, so the agent suggests and you send. |
| 4 | Push the analysis branch to the group's shared repository | No | Yes | Yes, the diff and test results can be checked | 1 | It leaves your control, so each step needs your approval, though it is checkable. |
| 5 | Delete intermediate files under results/tmp/ | No | No | Yes, a dry run lists them | 1 | It is local but cannot be undone, so each step needs approval. |
| 6 | Run the nightly parameter sweep and save results to a new folder | Yes | No | Yes, a check script validates the output | 3 | Local, reversible, and verifiable, so it can act and report. |
| 7 | Refactor an analysis script that has no tests | Yes | No | No | 2 | Reversible and local, but without tests the result cannot be checked quickly, so a human read is needed. |
| 8 | Submit a job that spends the lab's shared compute quota | No | Yes | Yes, the job's parameters can be reviewed | 1 | It leaves your control, so each step needs approval. |
Provenance: The levels and the assignment rule are from the section "Autonomy and Supervision" of this chapter. The tasks are invented for illustration, and the sim labels them "illustrative".
Rules: The level is computed from the three attributes in this order. If Leaves your control is Yes and Verifiable is No, the level is 0. If Leaves your control is Yes and Verifiable is Yes, the level is 1. If Leaves your control is No and Reversible is No, the level is 1. If Leaves your control is No, Reversible is Yes, and Verifiable is No, the level is 2. If Leaves your control is No, Reversible is Yes, and Verifiable is Yes, the level is 3.
Learner Activity:
- The learner sees task 1 with its three attributes.
- The learner chooses a level from 0 to 3 and submits.
- The sim shows whether the level was correct and the "Why" sentence, with the rule that applied.
- After task 8, the sim shows the count correct, and a summary of how many tasks fell at each level.
Feedback: Eight tasks, one attempt each, in a fixed order. Correct: "Correct: level
Starting State: Task 1 is shown with its three attributes and four levels, none chosen. The question on screen is "How much should the agent do on its own?"
Chapter Anchors: The chapter states four levels from 0 to 3, three properties (reversibility, reach, verifiability), and the assignment rule above, and that autonomy is set by the task and not by the model's capability.
MicroSim: Agent Autonomy Level Assigner. Open it fullscreen.
Logging, Failure Modes, and Runaway Agents¶
Agent logging is the recording of what an agent did, in a form you can read afterward. A useful log has, for each step, the time, the tool called and its arguments, the result or an excerpt of it, the files changed, the tokens used, and the model and settings in force. Logs serve three purposes: they let you audit what happened overnight, they let you debug a failure by finding the step at which things went wrong, and they let you reproduce a result. Keep them as plain files in or beside the project, so that they are searchable and, where appropriate, versioned.
Agents fail in recognizable ways, and naming the patterns is the first step to catching them. Agent failure modes commonly include the following.
- Premature completion: the agent reports success without having run the check that defines success.
- Hallucinated result: the agent reports a number or file that no tool produced.
- Scope drift: the agent fixes something nobody asked it to touch.
- Test weakening: faced with a failing test, the agent edits the test and not the code.
- Wrong arguments: the agent calls the right tool with the wrong path, parameter, or units.
- Runaway loop: the agent repeats an action without progress.
A runaway agent is an agent that continues acting beyond the point it should have stopped, by looping, spawning further work, or consuming resources without converging. The usual cause is a loop with no termination limit and a model that interprets each failure as a reason to try again. The defenses are mechanical: set a maximum number of steps, a time limit, and a budget on tokens or money; require that the agent stop and report when the same error recurs; and make destructive actions require approval.
Done Is a Claim, Not a Fact
A common trap is accepting an agent's statement that a task is complete. It happens because the report is fluent and the check is tedious. Make the check part of the task: require the output of the acceptance check in the report, and treat a "done" without it as unfinished.
Cost control is the set of limits and habits that keep agent spending predictable. Agents are expensive in a particular way. Each pass through the agent loop resends the growing context, so cost grows faster than the number of steps. A worked example with illustrative numbers shows the effect. The task starts with a 10,000-token context, and each iteration adds 2,000 tokens of tool results. At iteration \( i \) the input is \( 10{,}000 + 2{,}000(i-1) \) tokens. Over 10 iterations the total input is \( 10 \times 10{,}000 + 2{,}000 \times (0+1+\dots+9) = 190{,}000 \) tokens. Over 20 iterations it is \( 20 \times 10{,}000 + 2{,}000 \times (0+1+\dots+19) = 580{,}000 \) tokens. Doubling the steps roughly tripled the cost. At 3 dollars per million input tokens, the figures are about 0.57 and 1.74 dollars, small for one run and not small for a team of agents running all night.
The controls follow from the arithmetic. Set a step limit and a spending cap. Summarize or reset the context between phases. Use a smaller, cheaper model for routine steps and a stronger one only where it matters. Watch usage as a metric, and read the first few runs of any new workflow closely, since cost surprises appear at the beginning.
| Failure mode | What you would see in the log | Mechanical defense |
|---|---|---|
| Premature completion | "Done" with no check output | Require check output in the report |
| Hallucinated result | A number with no producing tool call | Trace every reported value to a call |
| Scope drift | Edits to files outside the request | Path permissions; review the diff |
| Test weakening | Test file changed with a failing code change | Protect tests, or review test diffs first |
| Wrong arguments | Tool errors, or results from the wrong file | Read the first calls of a new workflow |
| Runaway loop | The same call repeated many times | Step limit, repeat detector, spending cap |
Table 2. Failure modes, how they appear in a log, and a mechanical defense for each.
Diagram: Agent Failure Log Triage¶
Agent Failure Log Triage
Type: microsim
sim-id: agent-failure-log-triage
Library: p5.js
Status: Built
Bloom Level: Analyze
Bloom Verb: differentiate
Learning Objective: The learner will differentiate six agent failure modes from six excerpts of an agent log, with at least 5 of 6 attributed correctly.
Prerequisites: the six agent failure modes defined in the section "Logging, Failure Modes, and Runaway Agents" above.
Evidence of Mastery: For each of six log excerpts the learner commits one of six failure modes. A choice is correct when it equals the mode in Content. Mastery is at least 5 of 6 correct on the first attempt. Reading the definitions is exploration and is not evidence.
Misconceptions: (1) A passing test run means the work is correct. (2) An agent that touched extra files was being thorough. (3) Repeated tool calls mean the agent is working hard.
Instructional Rationale: Analyze-level work needs the learner to read raw evidence and attribute it to a cause. The excerpts are raw log lines, as a researcher would meet them, so that the skill transfers to real logs.
Content:
All excerpts are invented for illustration and labeled "illustrative".
| # | Log excerpt | Correct failure mode | Why (shown as feedback) |
|---|---|---|---|
| 1 | 14:02 tool=run_python args=scripts/enob.py rc=1 stderr="ValueError: need at least 64 samples". 14:02 agent: "All checks pass. The ENOB result is 9.4 bits." | Hallucinated result | The only run exited with an error, so no tool produced the value 9.4. |
| 2 | 14:10 tool=run_python tests/test_enob.py rc=1 (1 failed). 14:11 tool=edit_file path=tests/test_enob.py (changed expected value 10.0 to 9.0). 14:11 tool=run_python tests/test_enob.py rc=0. | Test weakening | The failing test was edited until it passed and the code was not changed. |
| 3 | 14:20 user request: "fix the typo in the README". 14:21 tool=edit_file path=README.md. 14:22 tool=edit_file path=scripts/enob.py (renamed 14 variables). 14:23 tool=edit_file path=docs/spec.md. | Scope drift | Edits to files that the request did not mention. |
| 4 | 14:30 tool=read_file path=data/rwa/capture-07.csv result=FileNotFoundError. 14:30 tool=read_file path=data/rwa/capture-07.csv result=FileNotFoundError. (repeated 31 times) | Runaway loop | The same failing call was repeated with no change and no progress. |
| 5 | 14:40 agent: "The conversion is complete." No tool calls since 14:35. The acceptance check scripts/check-units.py was never run. | Premature completion | Success was claimed without running the check that defines it. |
| 6 | 14:50 tool=run_python args="scripts/enob.py data/raw/capture-07.csv --fs 1000000" rc=0 result="ENOB=6.1". The record was sampled at 100000 Hz. | Wrong arguments | The tool ran with the wrong sampling rate, so the result is wrong without any error. |
Provenance: The failure modes are from the section "Logging, Failure Modes, and Runaway Agents" of this chapter. The log lines are invented for illustration.
Rules: Each excerpt has exactly one correct mode, chosen from the six: Premature completion, Hallucinated result, Scope drift, Test weakening, Wrong arguments, Runaway loop.
Learner Activity:
- The learner reads excerpt 1.
- The learner chooses one failure mode and submits.
- The sim shows whether it was correct, the "Why" sentence, and the mechanical defense for that mode from the chapter's Table 2.
- After excerpt 6, the sim shows the count correct.
Feedback: Six excerpts, one attempt each, in a fixed order. Correct: "Correct:
Starting State: Excerpt 1 is shown with the six modes listed. The question on screen is "What went wrong here?"
Chapter Anchors: The chapter lists six failure modes and states that a "done" claim must be backed by the check output and that a failing test should never be edited to pass.
MicroSim: Agent Failure Log Triage. Open it fullscreen.
Scheduling, Background Work, and Trust Boundaries¶
Task scheduling is arranging for an agent task to run at a set time or interval, such as a nightly literature sweep or a weekly rerun of an analysis when new data arrive. Background tasks are tasks an agent runs while you do other work, whether started now or by a schedule. The two share one hazard: nobody is watching. Before an agent runs unattended, four things should be true.
- The scope is narrow and written down: which files and tools it may use.
- The task is idempotent, which means running it twice gives the same result as running it once, so a repeated or interrupted run does no harm.
- It writes a log, and the log is where you look first the next morning.
- It has limits on steps, time, and spending, and it stops and reports when it hits them.
Agent evaluation is measuring how well an agent performs a task, as skill evaluation measured a skill in Chapter 7. The method is the same at a larger scale: a fixed set of tasks with known good outcomes, repeated runs because behavior varies, and a record of success rate, cost, and time. Evaluate an agent before you give it autonomy, and again after you change its model, tools, or instructions.
A trust boundary is a line between components or sources you trust and those you do not, across which data must be checked before it is acted on. For an agent, the content of a web page, an email, a downloaded paper, and the output of a third-party tool are all outside the boundary. The practical consequence is that text crossing the boundary is treated as data and not as instructions, and that the agent holding the most dangerous capabilities should read the least trusted text. Chapter 4 introduced prompt injection as the attack that exploits a missing boundary.
Credential handling is the discipline of managing secrets such as passwords, API keys, and tokens so that an agent can use a service without exposing the secret. The rules are short. Never put a secret in a prompt, an instruction file, a skill, or a repository. Provide secrets through environment variables or a secrets manager. Issue the narrowest credential that works: read-only where reading is enough, scoped to one project, and short-lived where the service allows it. Where possible, have the harness inject the credential at the moment of use, so that the model never sees it. Rotate any credential that may have entered a log or a context.
Defining Agent Roles¶
Supervising a single agent is a problem of attention. Supervising several is a problem of legibility: you must be able to say what each is for, what it may touch, and what it hands on. Agent roles are named responsibilities that divide work among agents, each with a defined purpose, inputs, outputs, tools, and autonomy level. A role is written once, as an agent specification file, and reused. Giving each agent one role has the same benefits as single-purpose skills: a narrow instruction set, a checkable output, and failures that localize.
Two roles frame the book's model of a team. A planning agent reads, explores, and decomposes: it surveys literature, breaks a problem into tasks, drafts specifications and acceptance criteria. Its output is a plan or a document, usually reversible and cheap to discard, so it can be given high autonomy and run in volume. An execution agent carries out a defined task: it writes code, runs analyses, builds simulations, prepares figures. Its output changes files and consumes resources, so it is bounded by its specification and its permissions, and its results are checked.
The planner-executor pattern is the arrangement in which a planning agent produces a specification and an execution agent carries it out, with the specification serving as the handoff. The pattern is effective for a reason that goes back to Chapter 4: the plan is a document you can read and correct before any execution happens, and the execution agent has an unambiguous task and acceptance criteria. It also reduces cost, because the strong, expensive model can plan and a smaller one can execute routine steps.
A reviewer agent is an agent whose job is to check another agent's output against stated criteria and report defects. It earns its keep because it works from the criteria and not from the producer's intentions, and it can be run by a different model, which gives some independence. It does not replace a human or a script. A reviewer shares the weaknesses of language models in general, so it complements tests and your own sampling instead of substituting for them.
Domain agents specialize an execution or planning role for one kind of research work:
- A literature agent searches, triages, and summarizes papers, and its output is a reading list with extracted claims. A research agent is the broader form that gathers and organizes information for a question.
- An analysis agent loads data, runs statistical and signal-processing steps, and produces tables and plots.
- A coding agent writes, runs, and debugs code, including simulation scripts and tests.
- A writing agent drafts and revises prose from notes and results, within the author's voice and the venue's conventions.
An agent handoff is the transfer of work from one agent to another. A handoff is where information is lost, so it is worth designing explicitly. A good handoff artifact states the goal, the inputs with their locations, the constraints, the acceptance criteria, what has been done, and what questions remain. It is a file, as in Chapter 1's workflow, so that you can read it. Context isolation is the practice of giving each agent only the context its role needs, and not the whole history, so that an agent is not distracted, cannot leak what it should not see, and cannot be misled by another agent's tangents.
| Role | Main job | Typical output | Typical autonomy | Typical check |
|---|---|---|---|---|
| Planning agent | Decompose, survey, specify | Plan, specification | 2 or 3 | Human read of the plan |
| Execution agent | Carry out a specified task | Files, results | 1 or 2 | Acceptance criteria, tests |
| Reviewer agent | Check output against criteria | Defect list | 3 | Sample of its findings |
| Literature agent | Search and summarize papers | Annotated list | 2 | Citation lookup |
| Analysis agent | Run analysis | Tables, plots | 2 | Known-answer tests |
| Coding agent | Write and test code | Scripts, tests | 2 | Tests, diff review |
| Writing agent | Draft and revise text | Section drafts | 2 | Author read; claim check |
Table 3. Agent roles and their usual outputs, autonomy levels, and checks. The levels refer to Table 1 and are starting points, not rules.
Write the Role as a Job Description
For each agent, write five lines: purpose, inputs, outputs, tools it may use, and when it must stop and ask. If you cannot fill in the last line, you have not decided its autonomy yet, and the agent will decide for you.
Summary and Key Takeaways¶
Agents can be given real work only when you can see what they do and bound what they can do. Autonomy is set per task, from reversibility, reach, and verifiability. Logs, limits, and checks make failures visible and bounded. Roles make a group of agents legible.
The main points to carry forward:
- Agent autonomy is a dial set per task by reversibility, reach, and verifiability, not by the model's capability.
- Supervision is the design of where a human looks. Logging makes the work auditable and reproducible.
- Agent failure modes, including premature completion, hallucinated results, scope drift, test weakening, wrong arguments, and runaway loops, each have a mechanical defense.
- Cost control uses step limits, spending caps, and context resets, because loop cost grows faster than the number of steps.
- Scheduled and background tasks need narrow scope, idempotence, logs, and limits before they run unattended.
- Trust boundaries and credential handling keep untrusted text as data and secrets out of the model's context.
- Roles such as planning, execution, reviewer, literature, analysis, coding, and writing agents divide work. The planner-executor pattern makes the plan a readable handoff.
- Handoffs and context isolation keep information from being lost or leaked between agents.
A Team You Can Read
You can now set an autonomy level from reversibility, reach, and verifiability, name the failure that a log line shows, and write a role as a job description with a stopping rule. That makes a group of agents something you can supervise.
The next chapter assembles these roles into coordinated teams, with task queues, handoff protocols, review checkpoints, and a candid look at when adding agents stops paying off. Round up the roles you would need for your project, and bring the list.