하위 작업은 자식에게 넘기고, 중단은 되돌려 받는다
읽는 데 약 35분분 걸린다, 7절에 4개 예제이(가) 있음.
AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식
영어판 2026.11.2판을 번역한 것이다. 원문 읽기
이 장을 마치면 자식 루프에 고유한 단계 예산을 주어 하위 작업을 맡기고, 자식의 전체 대화 기록 대신 요약과 중단 사유를 돌려받을 수 있다. 또한 중단이 사람에게 닿도록 만든다. 중단 규칙이 막힌 것으로 끝낸 실행은 부모에게 넘어가고, 부모는 그 중단의 질문을 이슈를 등록한 유지보수자에게 전한다.
사례의 작업 T-02를 보자. 작은 단위 라이브러리인 unitcraft에서 음수 금액이 천 단위 구분자를 잃는 문제가 있고, 유지보수 에이전트가 이를 고쳐야 한다. 실행은 unitcraft/format.py를 읽고 그 파일을 두 번 수정한다. 두 수정은 모두 실패한다. 수정이 지목한 기존 텍스트가 파일에 적힌 그대로 존재하지 않기 때문이며, 그래서 테스트 결과는 그대로다. 2장은 이처럼 진전이 없다고 규칙이 판단하면 실행을 끝낸다. 하니스 v1은 task-set 기록에서 T-02를 단계 상한까지 실행했다. 2장의 중단 규칙 두 가지를 모두 적용해 같은 응답을 다시 재생하면, 이 실행은 no_progress at step 5 of 16로 끝난다. 중단은 제 역할을 하지만, 유지보수자에게는 로그만 남고 에이전트가 무엇을 하려 했는지에 대한 설명은 남지 않는다. 그것을 알아내려면 누군가 로그를 읽어야 한다.
둘째 문제는 크기다. 반올림 규칙이 어디에 있는지 찾으려면 여러 파일을 읽어야 하고, 에이전트가 읽은 파일은 모두 다음 단계가 지니는 컨텍스트에 남는다. 이런 곁가지 작업은 별도의 컨텍스트에서 수행하고 부모에게 필요한 것만 돌려주는 편이 낫다. Anthropic의 서브에이전트 문서는 자사 제품에 대해 이러한 분리를 설명한다. 서브에이전트는 자신의 컨텍스트에서 작업을 수행하고 요약만 돌려준다.
이 장은 그 사례를 위한 자식을 만든다. 자식은 고유한 예산을 가진 같은 루프다. 이 책에서 핸드오프(handoff)는 실행이 완료로 끝나지 않고 사람에게 질문을 돌려주며 끝나는 것을 가리킨다. 모델이 직접 호출하는 ask_user일 수도 있고, 중단 뒤에 하니스가 내놓는 구조화된 핸드오프일 수도 있다. 후자는 중단 사유, 실행이 시도한 것, 질문을 담는다. 자식은 자신의 핸드오프를 부모에게 돌려준다. 여기에는 어떻게 끝났는지, 무엇을 시도했는지, 어떤 파일을 읽고 바꾸었는지, 그리고 요약 또는 멈춘 지점의 질문이 들어간다. 대화 기록은 결코 돌려주지 않는다. 자식을 끝낸 중단은 질문의 형태로 유지보수자에게 닿는다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
A child is a loop with its own budget
A side task in the case, such as finding where a rounding rule lives, can take steps that the parent's budget should not pay for. A child is the loop from chapter 1, started by a parent in the middle of its own run. It has the same tools and the same stop rules, and it keeps a transcript of its own. What differs is the count. The child's budget counts the child's own model calls, from its first call, so the parent's steps don't pay for the child's work, and a child that loops runs out of its own budget. That is the count chapter 5 promised a child: its own steps, not the parent's. A child's run_tests goes through the same sandboxed test runner as its parent's, with the caps, clean environment and no conftest files that chapter 7 describes, because the child is given the same tool set. The path is run_tests in lib/tools.py, then run_pytest and run_command there, then run_sandboxed in lib/sandbox.py. No example runs a child's command any other way.
Give the child 4 steps and run it on T-01. The task-set recording's first steps, from the model of chapter 1, replay for it, so the child does what the recorded run did at the start.
1"""A child loop on T-01 with a budget of 4 steps. The budget counts the child's own model calls, and it ends the child2as step_cap with no finish. The child's requests match the recording's first four steps, so they replay."""3from lib.case import load_tasks4from lib.models import ReplayModel5from lib.subagents import run_child6from lib.tools import V17from lib.trace import IdCounter89BUDGET = 410task = load_tasks(only=["T-01"])[0]11child = run_child(ReplayModel("task-set", "T-01"), task, V1, budget=BUDGET, ids=IdCounter())12print("child budget, steps:", BUDGET)13print("child steps:", child.handoff.steps)14print("child result:", child.handoff.ended)15print("child tools:", ", ".join(child.tool_names))16print("child steps, in order:", *child.trace, sep="\n ")17child.run.close()18assert child.handoff.ended == "step_cap" and child.handoff.steps == BUDGET
python child-with-budget.pychild budget, steps: 4
child steps: 4
child result: step_cap
child tools: list_files, read_file, run_tests, write_file, edit_file, ask_user, finish
child steps, in order:
step 1: list_files: 25 files
step 2: read_file: 23 lines
step 3: edit_file: error: old text not found in unitcraft/format.py
step 4: read_file: 23 lines
The budget, not the tools, ended this child: it used all its steps and never called finish. Its budget counts model calls, 4 of them here against a budget of 4, and the harness ends the child as step_cap. Its tools are the full tool set v1, list_files, read_file, run_tests, write_file, edit_file, ask_user, finish, so the budget is what holds the child back, not a smaller tool set.
Those 4 steps are the child's whole run. It lists the files, reads one, tries an edit that fails because the old text isn't in the file as written, and reads the file again. Nothing in the budget cares which of those steps was useful. It counts them.
A parent can start the same child itself, through a tool. In the next example the parent is a loop with two tools, start_child and ask_user. It starts the child on T-02 under both stop rules, reads the child's handoff as the tool's result, and asks the person the question the handoff carries.
1"""A parent loop starts the child on T-02 through a tool, reads the child's handoff and asks the person the child's2question. The output counts the parent's steps apart from the child's, and shows that the child's file text stays out of3the parent's context."""4from lib.case import load_tasks5from lib.loop import Stops, run_task6from lib.models import ReplayModel7from lib.subagents import ParentReadsHandoff, characters, start_child_tools8from lib.tools import V19from lib.trace import IdCounter1011RULES = Stops(repeat_limit=3, no_progress_limit=2)12task = load_tasks(only=["T-02"])[0]13child_ids = IdCounter()14child_ids.next("run") # the recording numbers its runs in task order, so T-02 is run-0002: skip T-01's number15children = []16tools = start_child_tools(task, lambda: ReplayModel("task-set", task.id), ids=child_ids, stops=RULES, children=children)17parent_model = ParentReadsHandoff(task.id)18parent = run_task(parent_model, task, tools, max_steps=tools.step_cap, ids=IdCounter())19child = children[0]20h = child.handoff21# the child's longest tool result is its read of the library file, the text a parent must not receive22file_text = max((m["content"] for m in child.transcript if m["role"] == "tool"), key=len)23parent_text = "\n".join(m["content"] for m in parent_model.messages)24print("child budget, steps:", V1.step_cap)25print("child steps:", h.steps)26print("child result:", h.ended)27print("parent steps:", parent.steps)28print("parent result:", parent.ended)29print("parent tools:", ", ".join(t.name for t in tools.tools))30print("question asked matches the handoff:", "yes" if parent.question == h.question else "no")31print("child transcript, characters:", characters(child.transcript))32print("handoff in parent context, characters:", len(h.text))33print("parent context at last step, characters:", characters(parent_model.messages))34print("child file text in parent context:", "yes" if file_text in parent_text else "no")35print("parent steps, in order:", *parent.trace.lines(), sep="\n ")36assert h.ended == "no_progress" and parent.ended == "ask_user" and parent.steps == 237assert parent.question == h.question and file_text not in parent_text38parent.close()
python parent-starts-child.pychild budget, steps: 16
child steps: 5
child result: no_progress
parent steps: 2
parent result: ask_user
parent tools: start_child, ask_user
question asked matches the handoff: yes
child transcript, characters: 5408
handoff in parent context, characters: 436
parent context at last step, characters: 1041
child file text in parent context: no
parent steps, in order:
step 1: start_child: child no_progress at step 5
step 2: ask_user: ask_user
The parent's question is the child's, word for word, and the child's file text is not in the parent's context. The child takes 5 steps of its own budget, and the parent takes 2, one to start the child and one to ask. The parent receives a handoff of 436 characters, where the child's transcript holds 5408.
The end is a stop like any other. A child that reaches its budget ends without a finish, and the handoff in the section on stops carries that end to the parent, which is where the next decision goes.
Working rule: Give each child a budget of its own, counted in its own model calls and never shared with the parent. Set it from runs that finished on the task set, not from a guess. A budget below what finished runs need turns finished work into stops.
네 부분으로 이루어진 브리프
브리프는 자식 에이전트가 받는 작업 그 자체다. 여기서 자식은 이슈 본문만 받는다. summary-to-parent의 T-02 자식은 해당 작업의 이슈에서 출발하며, 부모가 쓴 내용은 아무것도 받지 않는다. Anthropic의 멀티 에이전트 리서치 시스템 설명은 각 하위 에이전트의 브리프에 필요한 네 부분을 제시한다. 목표, 출력 형식, 사용할 도구와 출처에 대한 지침, 명확한 작업 경계다. 이 네 부분에 맞춰 쓰면 T-02 자식을 위한 브리프는 다음과 같을 수 있다.
Objective: find out why the two edits to unitcraft/format.py left the test result where it was.
Output format: a short summary, then the files read and the files edited.
Tools and sources: read_file and run_tests on the scratch copy; edit_file only on unitcraft/format.py.
Boundaries: do not change a test or any file other than unitcraft/format.py. If the fix needs a public name changed, call ask_user instead of editing.
각 부분은 T-02 사례에서 일어나기 쉬운 실패를 하나씩 막는다. 목표는 자식이 라이브러리의 나머지 부분이 아니라 두 가지 수정에만 집중하게 한다. 출력 형식은 부모가 결과를 한 번에 읽을 수 있게 하며, 파일 목록은 부모가 찾는 위치인 끝에 둔다. 도구와 출처 항목은 자식이 어느 파일을 수정해도 되는지 알려 준다. 이 예제의 자식은 write_file를 포함한 전체 도구 집합 v1을 갖고 있으므로, 이 항목은 부모가 쓰는 글일 뿐 여기서 이를 강제하는 장치는 없다. 이후 핸드오프의 files changed 줄은 자식이 어느 파일을 바꾸었는지 보여 주고, edits failed 줄은 적용되지 않은 수정이 몇 건인지 보여 준다. 경계는 유지보수자가 가장 먼저 확인하는 부분이다. 눈에 보이는 테스트가 곧 검증 수단이므로, 테스트를 고치면 수정 없이도 통과하기 때문이다.
브리프는 부모가 쓰는 글이며, 이 장은 그것을 측정하지 않는다. 같은 설명은 측정이 아니라 관찰로서, 모호한 작업을 받은 하위 에이전트들이 서로의 검색을 중복 수행하는 경우가 있었고 명시적인 브리프가 그 벤더의 해결책이었다고 보고한다. 여기에는 모호한 브리프를 시험하는 예제가 없다. 브리프가 확인 가능하게 만드는 것은 경계다. 되돌아오는 것에 관한 절의 핸드오프에는 자식이 읽고 바꾼 파일이 나열되며, 이를 경계 항목과 한 줄씩 대조할 수 있다.
작업 규칙: 자식을 시작하기 전에 브리프에 네 부분을 모두 쓰고, 경계는 의도가 아니라 파일과 도구로 적는다. 자식이 언제 끝나는지, 또는 어느 파일을 수정해도 되는지 말하지 못하는 브리프는 보낼 준비가 되지 않은 것이다.
돌아오는 것
T-02 실행은 읽은 모든 파일, 실패한 모든 편집, 실행한 모든 테스트의 기록을 남기며, 이는 부모가 돌려받아야 할 분량보다 훨씬 많다. 부모에게 필요한 것은 자식의 결과와, 그 결과를 판단할 만큼의 자식의 경로다. 파일을 읽은 기록은 필요하지 않다. 중단된 자식도 같은 방식으로 다루되, 중단 사유와 질문을 덧붙인다.
두 가지 중단 규칙을 모두 적용하고 작업 집합의 단계 상한을 둔 채 T-02를 자식으로 실행한 다음, 부모가 받는 내용을 자식의 기록 크기와 나란히 출력한다.
1"""T-02's recorded run as a child, with both stop rules and the task set's step cap. The parent gets the2handoff's fields and not the child's transcript; the example prints the size of each."""3from lib.case import load_tasks4from lib.loop import Stops5from lib.models import ReplayModel6from lib.subagents import characters, run_child, tokens7from lib.tools import V18from lib.trace import IdCounter910RULES = Stops(repeat_limit=3, no_progress_limit=2)11task = load_tasks(only=["T-02"])[0]12ids = IdCounter()13ids.next("run") # the recording numbers its runs in task order, so T-02 is run-0002: skip T-01's number14child = run_child(ReplayModel("task-set", "T-02"), task, V1, budget=V1.step_cap, ids=ids, stops=RULES)15h = child.handoff16print("child result:", h.ended, "at step", h.steps, "of", h.budget)17print("transcript messages:", len(child.transcript))18print("child transcript, characters:", characters(child.transcript))19print("child transcript, estimated tokens:", tokens(characters(child.transcript)))20print("parent receives, characters:", len(h.text))21print("parent receives, estimated tokens:", tokens(len(h.text)))22print("saved by the handoff, characters:", characters(child.transcript) - len(h.text))23print("what the parent receives:")24print(h.text)25child.run.close()26assert task.issue not in h.text and len(h.text) < characters(child.transcript)
python summary-to-parent.pychild result: no_progress at step 5 of 16
transcript messages: 12
child transcript, characters: 5408
child transcript, estimated tokens: 1803
parent receives, characters: 436
parent receives, estimated tokens: 146
saved by the handoff, characters: 4972
what the parent receives:
child: child-0001
ended: no_progress
steps: 5 of 16
tried: edit_file 2, list_files 1, read_file 2
files read: unitcraft/format.py
files changed: none
edits failed: 2
stop: no_progress (edit_file, 2 edits in a row left the test result unchanged: 8 failed, 22 passed)
question: The last 2 edits left the test result unchanged (last result: 8 failed, 22 passed). Should a person look at unitcraft/format.py, or should the agent keep going?
부모는 인계 내용만 받고 다른 것은 받지 않는다. 자식은 no_progress at step 5 of 16로 끝났고, 자식이 보관한 기록은 5408자에 이른다. 부모가 읽는 인계 내용은 436자다.
인계 내용의 files changed 줄은 none이고, edits failed 줄은 2이다. 두 편집 모두 unitcraft/format.py을 대상으로 했지만 파일의 바이트는 바뀌지 않았다. 그래서 changed 줄에서는 이 파일을 빼고, failed 개수가 편집이 적용되지 않았음을 알려 준다.
토큰으로 나타내면 같은 차이는 1803 대 146이다. 이 값은 모델의 토크나이저로 센 값이 아니라 5장의 규칙으로 추정한 값이며, 이 장은 크기를 비교하는 데에만 사용한다.
인계 내용의 줄은 정해진 순서로 나온다. 자식의 ID, 끝난 방식, 예산 대비 단계 수, 시도한 도구와 각 도구의 시도 횟수, 읽은 파일, 변경한 파일, 실패한 편집의 수, 그다음에 중단 사유와 질문이다. 작업을 마친 자식은 중단 사유와 질문 대신 요약을 제공한다. 완료된 자식은 개수만 세고 요약은 출력하지 않으므로, 요약 줄은 어떤 출력에도 나타나지 않는다. 예제는 이슈의 본문이 인계 내용에 그대로 나타나지 않는지 확인하며, 그래서 부모는 작업의 문구가 아니라 자식이 한 일을 바탕으로 판단한다.
부모가 인계 내용으로 무엇을 할지는 부모가 선택할 일이며, 이 장은 그것을 정해 두지 않는다. 이 장의 코드는 하나의 선택만 구현한다. 부모가 메인테이너에게 질문을 던지는 것이다. 같은 구성으로, 인계 내용에 나열된 파일을 지정한 더 좁은 지시문으로 두 번째 자식을 시작할 수도 있고, 필드만으로 답할 수도 있다. 어느 쪽도 예제로 구현하지는 않는다. 두 경우 모두 자식의 기록이 부모의 컨텍스트 밖에 남으며, 이것이 인계 내용을 두는 본래의 이유다.
자식 자신의 기록은 보관되며, 11장에서 추적하는 대상이 바로 이것이다. 부모는 이 기록을 열지 않는다.
작업 규칙: 부모에게는 자식의 ID, 끝난 방식, 개수, 파일, 그리고 중단 내용이나 요약만 돌려주고 그 이상은 돌려주지 않는다. 전사 기록은 추적에서 읽을 수 있도록 자식 자신의 기록에 남겨 둔다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
A stop handed back
The T-02 run ends stuck, and a stop alone doesn't tell the maintainer what to decide. Chapter 2 gave each stop a name and a reason, but someone still has to choose between taking the task from the agent, giving it more steps and trying another approach. That someone is the maintainer who filed the issue. So a stop that the harness can't resolve becomes a handoff to a parent, and the parent asks the maintainer.
The alternative is to log the stop and drop the run. That keeps the parent's context small, and it leaves the decision with nobody. The handoff keeps the decision with the maintainer, and costs the parent one short step in the runs below.
For the three stops that end a child stuck, step_cap, repeated_call and no_progress, the harness builds the handoff from the run's own record: its trace, its streak of repeated calls and its test counts. The stop reason, the counts and the question all come from that record. No model writes them, so a replayed run gives the same handoff every time. The parent is a loop of its own, with a small step budget and two tools, ask_user and finish. In a live design the parent would be a model that words the question to the maintainer. Here a scripted parent passes the question on exactly as the handoff gives it, so the run shows the wiring and not a model's judgement.
A child that ends some other way is not handed back. A run that ends as no_tool_call, for example, gives a handoff with no stop reason and no question, so the parent has nothing to put to the person. No run here ended that way (0 of the runs), so no example shows it.
Run every task-set run as a child under both stop rules. Each child that ends stuck goes to a parent, which asks the person its question.
1"""The 20 task-set runs as children, with both stop rules. Each child that ended stuck is handed to a parent, which2puts the stop's question to the person with ask_user. Counts only: how the children ended, and what the parents got."""3from collections import Counter45from lib.loop import Stops6from lib.models import ScriptedModel7from lib.subagents import STUCK, asks, characters, hand_to_parent, task_set_children8from lib.trace import IdCounter910RULES = Stops(repeat_limit=3, no_progress_limit=2)11ENDS = ("finish", "ask_user", "step_cap", "repeated_call", "no_progress", "no_tool_call")12children = task_set_children(RULES)13stuck = [(task, h, transcript) for task, h, _, transcript in children if h.stuck]14ends = Counter(h.ended for _, h, _, _ in children)15print("child runs:", len(children))16for ended in ENDS:17 print(f" {ended}: {ends[ended]}")18print("done with the rules:", sum(1 for _, _, ok, _ in children if ok))19print("ended with finish or ask_user:", sum(1 for _, h, _, _ in children if h.ended in ("finish", "ask_user")))20print("done among the handed back:", sum(1 for _, h, ok, _ in children if h.stuck and ok))21print("handed back to a parent:", len(stuck))22handed = Counter(h.ended for _, h, _ in stuck)23for ended in STUCK:24 print(f" {ended}: {handed[ended]}")25print("handed back, tasks:", ", ".join(task.id for task, _, _ in stuck))2627parent_ids = IdCounter() # the parents number their runs apart, so the children's run IDs stay the recording's28parents = [(h, hand_to_parent(ScriptedModel([asks(h.question)]), h, parent_ids)) for _, h, _ in stuck]29print("parent asked the person, with the handoff's question:",30 sum(1 for h, r in parents if r.ended == "ask_user" and r.question == h.question))31print("child steps, all handed back:", sum(h.steps for _, h, _ in stuck))32print("parent steps, all handed back:", sum(r.steps for _, r in parents))33print("child transcripts, characters:", sum(characters(t) for _, _, t in stuck))34print("handoffs the parents read, characters:", sum(len(h.text) for _, h, _ in stuck))35print("saved by the handoffs, characters:",36 sum(characters(t) for _, _, t in stuck) - sum(len(h.text) for _, h, _ in stuck))37assert all(h.stop and h.question for _, h, _ in stuck), "every stuck child gives a stop reason and a question"38assert not any(ok for _, h, ok, _ in children if h.stuck), "a done task must not be handed back"
python handoff-on-stuck.pychild runs: 20
finish: 6
ask_user: 1
step_cap: 1
repeated_call: 1
no_progress: 11
no_tool_call: 0
done with the rules: 5
ended with finish or ask_user: 7
done among the handed back: 0
handed back to a parent: 13
step_cap: 1
repeated_call: 1
no_progress: 11
handed back, tasks: T-01, T-02, T-03, T-06, T-10, T-11, T-12, T-13, T-15, T-16, T-17, T-19, T-20
parent asked the person, with the handoff's question: 13
child steps, all handed back: 83
parent steps, all handed back: 13
child transcripts, characters: 95252
handoffs the parents read, characters: 5874
saved by the handoffs, characters: 89378
None of the runs a stop handed back was done. The rules hand back 13 of the 20 runs, and none of those is done. Each one reaches a parent, and the parents put the question to the person 13 times, once for each. The stop that comes up most is no_progress, the same stop T-02 ended on.
The stop rules cost no finished work. 7 runs ended with finish (6) or with ask_user (1), and all 5 done runs are among them, because none of the handed-back runs was done. The other runs in that group are not done, and none of them ended on a stop rule, so no handoff covers them. A run that ends with finish or ask_user never reaches a parent under these rules, whether or not it was right to end there.
The handed-back runs are T-01, T-02, T-03, T-06, T-10, T-11, T-12, T-13, T-15, T-16, T-17, T-19, T-20. Between them their children took 83 steps, and their parents took 13 steps, one each, the call that asks the person.
The children's transcripts held 95252 characters, and the parents read 5874 characters of handoff between them. Every handed-back child is checked to give a stop reason and a question. That checks the shape of the handoff, and it doesn't check that the question is the right one to ask.
The question for the T-02 run ends: "Should a person look at unitcraft/format.py, or should the agent keep going?" It names the file that both failed edits named, so the maintainer knows where to look without opening the transcript. The handoff's files changed line says no file changed, so the question points at a file the edits named but never changed.
One caveat, said once: a handoff says that a run stopped and why. It doesn't say the task could not be finished. This book counts a handed-back run as not done, as the example does.
Working rule: Hand every stuck stop (step_cap, repeated_call, no_progress) to a person as a question, with its stop reason, its counts and its files. A parent works from the handoff. The child's record stays with the child, where a trace can read it.
두 가지 설계와 수치의 출처
분할에 어떤 설계를 쓸지는 부모가 자식의 결과로 무엇을 해야 하는지에 달려 있다. 널리 쓰이는 설계는 두 가지이며, 두 설계는 대화에 일어나는 일에서 다르다. 이 장의 설계에서는 자식이 결과를 반환하고 멈춘다. SDK의 핸드오프에서는 대화가 다른 에이전트로 넘어간다. SDK는 두 번째 설계를 핸드오프라고 부르는데, 이는 이 장에서 쓰는 핸드오프의 뜻이 아니다. 이 절의 어떤 내용도 여기서 실행하지 않았으며, 여기에 나오는 수치는 각 출처의 것이다.
OpenAI Agents SDK의 핸드오프 문서는 2026년 11월에 가져온 SDK 0.24.0 기준으로 두 번째 설계를 설명한다. 핸드오프는 모델이 호출하는 도구이며 대상의 이름을 따서 붙인다. 문서의 예는 transfer_to_refund_agent이다. 입력 필터가 보이는 내용을 바꾸지 않는 한, 넘겨받은 에이전트는 이전 대화 전체를 본다. 대화를 넘겨받지 않고 결과만 반환해야 하는 전문 에이전트에는 같은 문서가 Agent.as_tool로 에이전트를 도구로 감싸라고 권한다. 이전 대화를 요약하는 중첩 이력은 선택해서 켜는 베타 기능이며 기본값은 꺼짐이다.
Claude Code 서브에이전트 문서는 2026년 11월에 가져온 기준으로 첫 번째 종류를 설명한다. 서브에이전트에는 에이전트 턴 수의 한도가 있으며, 이 책에서는 이를 단계라고 부른다. 이 한도는 maxTurns로 설정한다. 서브에이전트가 한도에 도달하면 출력이 부분 결과로 표시되어 돌아오고, 부모는 그 서브에이전트를 재개할 수 있다. 문서는 부분 결과 표시에 "Claude Code v2.1.246 이상이 필요하다"고 적고 있으며, 이 버전에서는 아무것도 실행하지 않았다. 기본 제공 서브에이전트는 부모의 권한 규칙을 상속하고, 대부분 제한된 도구 집합으로 실행된다. 사용자 정의 서브에이전트는 자체 도구와 독립된 권한을 가진다. 이 형태는 이 장의 예산과 일치하며, 여기서는 이 장의 핸드오프가 부분 결과의 역할을 한다.
이 절에서 인용하는 측정은 측정 대상인 시스템을 만든 회사에서 나왔다. 2025년 6월 Anthropic의 연구 시스템 설명은 "Claude Opus 4를 리드 에이전트로, Claude Sonnet 4를 서브에이전트로 쓴 멀티 에이전트 시스템이 내부 연구 평가에서 단일 에이전트 Claude Opus 4보다 90.2% 높은 성능을 보였다"고 보고했다. 이 비교는 멀티 에이전트 시스템을 에이전트 하나와 맞세운 것이고, 서브에이전트에는 다른 모델을 썼으며, 글이 지표를 밝히지 않은 평가에서 얻은 것이다. 글은 자사의 평가가 너비 우선 질의에 유리하다고 밝힌다. 이런 질의에서는 서로 독립된 여러 방향을 동시에 탐색할 수 있다.
같은 글은 BrowseComp 평가에서 얻은 두 번째 측정도 제시한다. "토큰 사용량만으로 분산의 80%가 설명된다"는 것이다. 글은 멀티 에이전트 시스템이 잘 작동하는 주된 이유가 문제를 풀기에 충분한 토큰을 쓰기 때문이라고 말한다. 글의 자체 데이터에서 에이전트는 채팅의 약 4배, 멀티 에이전트 시스템은 약 15배의 토큰을 썼다. 또한 에이전트들이 하나의 컨텍스트를 공유해야 하거나 서로 여러 방식으로 의존하는 일부 영역은 적합하지 않다고 하며, 리드 에이전트가 서브에이전트를 묶음으로 실행하고 각 묶음이 끝나기를 기다렸다고 한다. 에이전트가 여럿이라고 해서 분할이 병렬이 되는 것은 아니다.
분할에 반대하는 널리 읽힌 논거는 2025년 Cognition이 게시한 Walden Yan의 에세이 "Don't Build Multi-Agents"에서 나온다. 첫 번째 원칙은 "컨텍스트를 공유하라. 개별 메시지만이 아니라 에이전트의 전체 트레이스를 공유하라."이다. 핸드오프는 이 원칙을 어긴다. 핸드오프는 자식의 필드와 요약 또는 중단 사실을 넘길 뿐, 전체 트레이스는 넘기지 않는다. 에세이의 두 번째 원칙은 행동에 암묵적 결정이 담겨 있으므로, 따로 일하는 에이전트들이 서로 충돌하는 결정에 따라 행동할 수 있다는 것이다. 이는 에세이이며, 한 실무자의 판단이다.
에세이가 원칙을 따르는 가장 단순한 방법은 연속된 컨텍스트를 가진 선형 에이전트 하나를 쓰는 것이다. 아주 긴 작업에는 이력을 핵심 세부 사항, 사건, 결정으로 압축하는 모델을 제안하며, 이를 제대로 만들기는 어렵다고 말한다. 이는 5장의 컴팩션과, 그리고 이 핸드오프와 가깝다. 에세이는 또한 명확하게 정의된 질문에 답하는 서브에이전트, 대개 코드를 전혀 작성하지 않는 서브에이전트는 받아들인다.
이 장의 예제 자식은 코드를 작성한다. T-02의 자식은 unitcraft/format.py를 수정하는데, 이는 에세이가 반대하는 경우다. 여기서는 자식 하나가 수정하고 부모는 그 파일을 수정하지 않으므로, 두 번째 원칙이 설명하는 충돌은 이 예제들에서 일어나지 않는다. 그래도 자식이 수정한 이유는 부모에게 전달되지 않으며, 이에 대한 에세이의 반론은 여전히 유효하다. 그럼에도 이 책이 자식을 만드는 것은 T-02의 경우에 라이브러리를 바꿀 수 있는 자식이 필요하기 때문이다. 분할이 이득이 되는 경우는 결과를 그 이유 없이도 쓸 수 있을 때이며, 이는 제품 문서가 설명하는 경우다.
결과가 독립적으로 쓰이는 부수 작업에는 자식을, 부모와 자식이 같은 파일을 수정하게 될 작업에는 루프 하나를 권한다.
작업 규칙: 결과를 이유 없이도 쓸 수 있을 때, 즉 사실 하나, 파일 목록, 또는 질문이 담긴 중단일 때 자식을 쓴다. 자식이 수정할 파일을 부모가 직접 다루어야 하면 루프 하나를 유지한다. 이 책은 분할을 루프 하나와 비교해 측정하지 않으므로, 이 규칙은 측정이 아니라 위의 논거에 근거한다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
What goes wrong in production
Splitting work brings failures that a single loop doesn't have. The first is a budget in the wrong unit. A budget counted in seconds stops a child for a slow test run as readily as for a loop, and a replay can't repeat it, because the same run takes a different time each time. That is why this chapter counts model calls and no time.
The second is a parent that decides for the person. The parent in handoff-on-stuck has finish as well as ask_user among its tools, so a model that thinks it knows the answer can end a stuck run without asking anyone. In production, a parent handed a stop should have only the means to ask, and a stop that reaches it should always end with a question to the maintainer.
The third is a split the parent can't reconcile. Two children that edit the same file can each hand back a clean summary, and the parent then has to open both records to see that their edits disagree. The handoff doesn't show that disagreement by itself, which is the point of the counter-view.
The fourth is cost that doesn't show. A child's tokens are its own, and the vendor's figure puts a multi-agent system at about fifteen times a chat's tokens. Trace each child's tokens on its own record, as chapter 11 does, or the cost of a split never reaches the parent's count.
Working rule: Count a child's budget in model calls, give its parent only the means to ask, and check each split's edits against the files the other children changed before you merge them. Trace each child's tokens on its own record, so a split's cost is counted where it is spent.
이 장에서 내린 결정
유지보수자에게 달라지는 점은 T-02 중단이 이제 파일 하나에 대한 질문으로 도착한다는 것이다. 예전에는 유지보수자가 읽어야 하는 로그로 끝났고, 거기에는 내려야 할 결정이 붙어 있지 않았다. 이 설계에서는 중단이 관련 파일과, 살펴볼 파일을 짚는 질문과 함께 유지보수자에게 전달된다. 아래의 각 선택은 바꿀 수 있으며, 각각 실행이 잘못되었을 때 유지보수자가 보는 내용을 바꾼다. 처음 세 가지는 자식이 얼마를 쓸 수 있는지, 무엇을 돌려주는지, 중단의 이유가 어디서 오는지를 정한다. 나머지 세 가지는 언제 자식을 떼어 낼 만한지, 자식이 끝내지 못할 때 누가 답하는지를 정한다.
- 자식의 예산은 자식 자신의 모델 호출을 센다. 부모의 호출 횟수에는 자식의 호출이 포함되지 않는다.
- 자식은 필드와 요약 또는 중단을 돌려주며, 대화 기록 전체는 돌려주지 않는다. 대화 기록은 자식 자신의 기록에 남는다.
- 중단의 이유, 횟수, 질문은 코드가 만든 실행 기록에서 가져오므로, 다시 실행해도 같은 인계가 나온다.
- 막힌 자식은 단계 예산이 작은 부모에게 넘어가고, 부모는
ask_user를 통해 이슈를 등록한 유지보수자에게 묻는다. - 자식은 결과가 독립적으로 성립하는 부수 작업을 위한 것이다. 부모와 자식이 같은 파일을 편집하는 작업은 하나의 루프 안에 둔다.
- 질문으로 사람에게 전달되는 중단이 로그로 끝나는 중단보다 더 유용하다. 12장은 어떤 분할도, 어떤 에이전트도 그 비용만큼의 가치가 없는 경우를 다룬다.
이 판의 이 장
2026.11.2판예제 통과 2026년 11월 20이 장에서 4개 예제개 중 4개가 통과한다
영어판 2026.11.2판을 번역한 것이다.