Agentic Architecture & Orchestration flashcards

Every card in this deck

The whole deck as a list, for scanning or printing.

What are the two stop_reason values the exam keys the agentic loop on?

tool_use (continue the loop) and end_turn (terminate the loop).

List the full stop_reason enum documented in the Messages API.

end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal, model_context_window_exceeded.

How should a loop handle pause_turn?

Append the assistant's response to messages and make another request to let Claude continue — do not treat it as finished.

What are the three fields on a tool_use content block?

id, name, input.

Which role carries a tool_result block?

user — there is no separate "tool" or "function" role in the Messages API.

What are the two placement rules for tool_result messages?

1) tool_result must immediately follow the tool_use message (no messages in between). 2) All tool_result blocks must come before any text in that message.

Where does disable_parallel_tool_use live in the request?

Inside the tool_choice object, not as a top-level parameter.

What role should an iteration cap play in an agentic loop?

A safety bound (e.g. SDK's max_turns), never the primary stopping mechanism — that's always stop_reason.

Why is checking response.content[0].type == "text" wrong for detecting loop completion?

Claude can return text alongside tool_use blocks in the same response; text presence doesn't indicate the agent is finished.

How many times does Claude typically retry an invalid/missing-parameter tool call before apologising?

2-3 times, with corrections.

What is Anthropic's formal name for the hub-and-spoke coordinator-subagent pattern?

Orchestrator-workers.

What is the defining trait that separates orchestrator-workers from the parallelization pattern?

In orchestrator-workers, subtasks are NOT pre-defined — they're determined dynamically by the orchestrator. In parallelization, subtasks are fixed in advance.

Roughly how many more tokens do agents use versus a chat interaction? Multi-agent systems?

Agents: ~4x. Multi-agent systems: ~15x.

What was the measured performance uplift of an Opus 4 lead + Sonnet 4 subagents system over single-agent Opus 4?

90.2%.

Anthropic's research prompts scale agent count to query complexity. What are the three documented tiers?

Simple fact-finding: 1 agent, 3-10 tool calls. Direct comparison: 2-4 subagents, 10-15 calls each. Complex research: 10+ subagents.

Why shouldn't a coordinator route every query through its full subagent pipeline?

Dynamic subagent selection is a coordinator responsibility — a simple factual question may need only the search subagent. Routing everything through the whole chain pays the ~15x multi-agent token premium for no accuracy gain.

What are the two levels of parallelization in a multi-agent research system?

Lead agent spins up 3-5 subagents in parallel; each subagent uses 3+ tools in parallel.

A report on 'renewable energy' only covers solar and wind despite all subagents working correctly. What's the root cause?

The coordinator's task decomposition was too narrow — it never assigned geothermal, tidal, biomass, or fusion to any subagent.

What causes the 'duplicated work' delegation failure mode (distinct from narrow decomposition)?

Vague per-subagent task descriptions — e.g. two subagents both research 2025 supply chains while nobody covers the 2021 chip crisis.

Name two domains where multi-agent orchestration is documented as a poor fit.

Domains requiring shared context or many dependencies across agents, and most coding tasks (fewer parallelizable subtasks than research).

What is the exam-guide name for the subagent-spawning tool, and what is its current Claude Code name?

Exam guide: "Task". Current Claude Code (v2.1.63+): "Agent" — Task still appears in the system:init tools list.

Which two AgentDefinition fields are required? Which two are optional?

Required: description, prompt. Optional: tools (string[]), model.

What happens if you omit the tools field in an AgentDefinition?

The subagent gets every tool available to subagents (not restricted) — omitting is permissive, not restrictive.

What model alias values does AgentDefinition.model accept?

'fable', 'opus', 'sonnet', 'haiku', 'inherit', or a full model ID; defaults to the main model if omitted.

What are the three ways to create a subagent?

Programmatically (agents option in query()), filesystem-based (.claude/agents/ markdown files), and the built-in general-purpose subagent.

If a programmatic and a filesystem subagent share a name, which wins?

The programmatic definition takes precedence.

How does Claude decide whether to invoke a given subagent automatically?

Based on that subagent's description field — a subagent can also be explicitly requested by name in the prompt.

What is the ONLY content that crosses from a parent to a subagent?

The Agent tool's prompt string — no conversation history, system prompt, or other subagent's output unless explicitly included in that prompt.

What happens to a subagent's intermediate tool calls and results?

They stay inside the subagent — only its final message returns to the parent.

Why do parallel subagents finish faster than sequential ones?

Independent subtasks finish in the time of the slowest one rather than the sum of all of them — safe because each subagent has its own isolated context window.

What does fork_session / forkSession do, and what's its default?

When resuming, forks to a NEW session ID instead of continuing the original session. Boolean, default false.

What exactly does a session fork preserve, and what happens to the original?

A copy of history up to the fork point; the original's ID and history stay completely unchanged — two independently resumable sessions result.

What is the SDK's documented permission evaluation order (all six steps)?

Hooks → deny rules → ask rules → permission mode → allow rules → canUseTool callback.

Does a matching deny rule block a tool even in bypassPermissions mode?

Yes — deny rules block the tool even in bypassPermissions mode.

Does a hook returning 'allow' skip the deny and ask rules?

No — a hook allow does not skip deny/ask rules; those are still evaluated regardless of the hook result.

When is canUseTool actually invoked?

Only when the permission flow falls through to a prompt — it's skipped for calls auto-approved by allowedTools, allow rules, acceptEdits, or bypassPermissions.

What's the correct mechanism for a check that must run on EVERY tool call, regardless of permission mode?

A PreToolUse hook — hooks run before every other step, and a hook deny applies even in bypassPermissions mode.

What's the difference between disallowedTools: ["Bash"] and disallowedTools: ["Bash(rm *)"]?

Bare "Bash" removes the tool definition entirely (Claude can't see or attempt it). Scoped "Bash(rm *)" keeps Bash visible; only matching calls are denied, in every mode.

What is the exam's decision rule for choosing programmatic enforcement over prompt guidance?

If a single failure would cause financial loss, security breach, or compliance violation, use programmatic enforcement (hooks/gates); prompt guidance is fine for low-stakes preferences.

What 5 fields must a structured handoff summary to a human agent include?

Customer ID, conversation summary, root cause analysis, refund amount (if applicable), recommended action.

Why must a handoff summary be self-contained?

The human agent does NOT have access to the conversation transcript — the summary is the only information they receive.

How should multi-concern customer requests be handled?

Decompose into distinct items, investigate each in parallel using shared context, then synthesise a single unified resolution — not sequentially or by addressing only the first item.

Which hook events are available in BOTH the Python and TypeScript Agent SDKs?

PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Notification.

Which two hook events are TypeScript-only?

SessionStart and SessionEnd.

What does a HookMatcher's matcher field do?

Tests a pattern (e.g. "Write|Edit", or a regex like ^mcp__) against the event's target, usually the tool name. No matcher = the hook runs for every event of that type.

What are the four values a PreToolUse hook's permissionDecision can take?

allow, deny, ask, defer.

What does updatedInput do when paired with permissionDecision: 'allow'?

It rewrites the tool's input and auto-approves the modified call, without prompting the user.

What happens if updatedInput is returned with no permissionDecision set?

The modified input still applies, but it flows through the normal permission evaluation instead of being auto-approved.

What's the difference between PostToolUse's additionalContext and updatedToolOutput?

additionalContext appends info alongside the original result. updatedToolOutput replaces the tool's output before Claude sees it (works for any tool, both SDKs).

For normalising heterogeneous tool output so the model never sees the raw format, which PostToolUse field is correct?

updatedToolOutput — it replaces the result rather than appending alongside the raw data.

What is the decision priority when multiple hooks or rules apply to the same call?

deny > defer > ask > allow. Any single hook deny blocks the operation regardless of other hooks.

What does returning {} from a hook mean?

Allow the operation without changes.

What two top-level fields apply to every hook output regardless of event type?

systemMessage (message shown to the user) and continue/continue_ (whether the agent keeps running after this hook).

Why is a PostToolUse hook the wrong choice for blocking a policy-violating action like an over-threshold refund?

PostToolUse fires AFTER the tool has already executed — the non-compliant action has already happened by the time the hook runs.

What is Anthropic's formal name for 'fixed sequential pipelines'?

Prompt chaining.

What is the main goal of prompt chaining?

Trade latency for higher accuracy by making each LLM call an easier task.

What is a 'gate' in a prompt chain?

A programmatic check on an intermediate step's output before the chain proceeds.

What is Anthropic's formal name for 'dynamic adaptive decomposition'?

Orchestrator-workers.

Name the three other named workflow patterns besides prompt chaining and orchestrator-workers.

Routing, parallelization (sectioning and voting), and evaluator-optimizer.

What's the difference between parallelization's sectioning and voting sub-patterns?

Sectioning: independent subtasks run in parallel. Voting: the SAME task run multiple times for diverse outputs (e.g. multiple vulnerability-review passes).

When does evaluator-optimizer work best?

When there are clear evaluation criteria and iterative refinement provides measurable value (e.g. literary translation with a critic LLM).

What does dynamic decomposition need at each step to adapt correctly?

"Ground truth" from the environment — real tool results, test runs, actual file contents — not just prior assumptions.

What is attention dilution, and what are its telltale symptoms?

Inconsistent analysis depth from processing too many items in one pass — thorough feedback for early items, shallow for later ones, and the same pattern flagged in one item but approved in another.

What is the structural fix for attention dilution?

Multi-pass architecture: per-item local analysis passes (each gets full attention budget) plus a separate cross-item integration pass for cross-cutting concerns.

Does a bigger model or larger context window fix attention dilution?

No — it's an architectural/attention-allocation problem, not a model capability problem.

Where are Claude Code sessions stored on disk?

~/.claude/projects/<encoded-cwd>/*.jsonl, where encoded-cwd replaces every non-alphanumeric character with a dash.

What's the most common cause of --resume returning a fresh, empty session?

Running resume from a different working directory than the one the session was created in.

What does a resumed session restore?

Full conversation history (tool calls + results), model, agent, permission mode, goals, and unexpired scheduled tasks.

Which two permission modes are NEVER restored on resume?

plan and bypassPermissions.

What's the difference between --continue and --resume?

--continue finds the most recent session in the current directory with no ID tracking. --resume takes a specific session ID or name that you must track.

You fork a session to try a second approach. What do you now see in the session picker, and can you get back to the first?

Two independent rows — the fork and the original. The original's ID and history are untouched, so both remain separately resumable.

Do sessions persist file changes made by the agent?

No — sessions persist the conversation only, not the filesystem. File snapshots/reverts are a separate mechanism: checkpointing.

What is checkpointing's blind spot?

It does not track files modified via Bash commands — only direct edits made through Claude's own file-editing tools are tracked.

Why is resuming after file changes worse than just asking the agent to re-read the changed files?

Stale tool results from before the changes remain in conversation history and can still influence reasoning on tangential decisions, even after the agent re-reads the modified files.

What is the correct fix for the stale context problem after file modifications?

Start a fresh session with an injected structured summary of prior findings, specifying which files changed for targeted re-analysis — not a naive resume.

Why is fork_session the wrong tool for fixing stale context?

A fork branches from the existing session, which still contains the same stale tool results — the fork inherits the contamination rather than clearing it.

In headless/CI scripting, how do you capture a session ID to resume later?

claude -p "..." --output-format json | jq -r '.session_id' — then pass that ID to --resume from the same project directory.

What can a SubagentStart hook do, and what can't it?

It observes: it receives the subagent's type and id, and can log the spawn or inject context into the run. It cannot block or modify the invocation — to gate spawning itself, put a PreToolUse hook on the Agent tool.

How does a SubagentStop hook gate a subagent's completion?

By returning decision: "block" with a reason, which sends the subagent back to keep working instead of letting it finish. It cannot rewrite the returned output — that's a PostToolUse updatedToolOutput on the Agent tool call.

Should a coordinator's subagent prompts specify goals or step-by-step procedures?

Goals and quality criteria. Procedural instructions constrain the subagent and stop it adapting when it hits a situation the coordinator never anticipated.