1.1 Agent Architecture
- Workflow: code chooses the next step. Agent: the model chooses the next step.
- Known path → workflow. Discovered path → agent. Tie → workflow.
- One tool-use loop is an agent. Multi-agent is optional.
- Supervisor decomposes, delegates, and aggregates. Subagents do not share memory.
- Pass context explicitly. Only the subagent's final message returns.
- Sequential when there is a data dependency. Parallel when there is not.
- stop_reason is the loop control. An iteration cap is a safety ceiling.
- Side effects stay behind code, even when the investigation is an agent.
| If the question says... | The answer is likely... |
|---|---|
| "identical steps every run" | Workflow |
| "depends on what the lookup returns" | Agent |
| "either would work" | The simpler one, usually the workflow |
| "a single tool loop" | Already an agent |
| "report missed a whole category" | Supervisor decomposition, not the worker |
| "file bodies flooding the parent" | Subagent isolation |
| "step needs the previous output" | Sequential |
| "independent slices" | Parallel, then fan-in |
| Trap | Correct answer |
|---|---|
| Default to an agent because it is more capable. | Capability is the model and the tools. The structure is about control. |
| An agent means several agents. | One loop that chooses its own tools is an agent. |
| A known if-statement requires an agent. | A branch you can write is still a workflow. |
| Raise the iteration cap to fix an early stop. | Completion is end_turn. The cap only prevents a runaway. |
| Subagents read the parent transcript. | They see the prompt you pass. Put the facts in it. |
| Parallelise a write that depends on a check. | The check and the write are sequential. |
1.2 Agent Construction with Claude
- SDK provides the loop, tool dispatch, and sessions. You provide prompt, tools, and permissions.
- The SDK is a layer on the Messages API, not a different model.
- Custom loop: send, read stop_reason, run tools, append results, repeat until end_turn.
- Do not stop on prose. Do not treat max_tokens as success.
- PreToolUse can block. PostToolUse cannot undo.
- Human approval is a harness pause, not a prompt sentence.
- Anthropic-hosted sandbox: least infrastructure. Self-hosted sandbox: residency.
- Hosted Managed Agents is not the ZDR or HIPAA BAA path.
- Iteration and spend caps are safety nets beside end_turn.
| If the question says... | The answer is likely... |
|---|---|
| "SDK will fix wrong tool choice" | No. Fix descriptions and permissions. |
| "need custom retries and traces" | Custom harness |
| "standard loop in our process" | Agent SDK |
| "do not operate a sandbox" | Managed Agents, Anthropic-hosted |
| "data must stay in our VPC" | Self-hosted sandbox or your own process |
| "must never refund above N" | PreToolUse or omit the tool |
| "stop when the text looks done" | Wrong. Branch on stop_reason. |
| "PostToolUse to prevent the delete" | Wrong. The delete already ran. |
| Trap | Correct answer |
|---|---|
| The SDK replaces the Messages API. | It calls the API and adds the loop. |
| A firm prompt guarantees a destructive action will not happen. | Use a hook or remove the tool. |
| Self-hosted means you must write the loop. | Self-hosted can be the sandbox under Managed Agents. |
| Hosted agents are fine for a ZDR contract. | Hosted session state is stored server-side. |
| A tool error should be an empty success so the loop stays simple. | Return the error as a tool result or fail the turn. |
| Ask the model to request approval. | The harness pauses until a person responds. |
1.3 Agent Patterns and Frameworks
- Tool loop: tool_use continues, end_turn stops, results are appended.
- Subagent context is isolated. Pass the slice. Accept the final message.
- Parallel subagents are multiple delegations in one parent turn.
- Working context is what you send. Durable memory is what you store and load later.
- A bigger window is not the first fix for tool-log bloat.
- Prune one huge result. Compact a long thread. Isolate an exploration.
- Frameworks standardise loop control, state, and branching.
- They do not raise model capability.
- LangGraph: explicit graph and checkpoints. PydanticAI: typed results. Strands: model-driven loop.
- Skip the framework when a single tool loop is the whole design.
| If the question says... | The answer is likely... |
|---|---|
| "single tool until done" | Plain loop, not a framework |
| "make the model smarter" | Not what a framework does |
| "checkpoints and human interrupt" | A state graph such as LangGraph |
| "typed result and dependencies" | A typed agent layer such as PydanticAI |
| "model-driven loop, little graph code" | A library such as Strands |
| "parent drowned in page fetches" | Subagent returns a cited excerpt |
| "remember this next session" | Durable memory, retrieved on purpose |
| "contradicts early constraints" | Prune, compact, or isolate. Not temperature. |
| Trap | Correct answer |
|---|---|
| LangGraph raises answer quality. | It changes orchestration. Quality comes from the model, prompt, and tools. |
| Any multi-tool agent needs a framework. | Several tools in one loop are still one loop. |
| Memory writes expand the context window. | They expand storage. Loading them all fills the window again. |
| Repeat the system prompt every turn to cure drift. | Remove the stale tool output that is crowding it. |
| Merge the subagent transcript into the parent to be safe. | That discards isolation. Define the return fields. |
| Future-proof by adopting the heaviest graph now. | Pay for a graph when the branches exist. |