Agent patterns and frameworks: workflows, subagents, and memory

1.The five workflow patterns and when an agent fits instead

Start with the simplest design and add structure only when a measured gain pays for it. Agentic systems usually trade latency and cost for better task performance. For many applications, a single well-prompted LLM call with retrieval and a few examples is enough. When it isn't, there are five standard workflow shapes. In each one your code fixes the path, and the model does the work at each step.

Parallelization and orchestrator-workers both split work, and they are the pair candidates confuse most often. In sectioning, the subtasks are fixed in code before the run starts. In orchestrator-workers, the model decides the subtasks at runtime. Voting is a different case: it runs the same task several times, such as several prompts each reviewing code for vulnerabilities, and combines the verdicts. Running the parts at the same time also cuts wall-clock time, because concurrent subagents finish when the slowest one finishes, not after the sum of all of them.

Sources12

2.Who drives the tool-use loop

Every agent runs the same cycle: Claude asks for a tool, the tool runs, and the result goes back to Claude. That cycle is covered in [the tool-use (agentic) loop](lesson:8.1). The design choice is who drives it. The answer decides what your code is responsible for and how much of the cycle you can see.

Whoever drives the loop decides what to do next by reading the stop_reason on each API response, which reports why Claude stopped generating. "tool_use" means Claude wants a client tool run, and "end_turn" means it produced a final answer; "max_tokens", "stop_sequence", and "refusal" are other stops your code has to handle. "pause_turn" belongs to server tools: their internal loop has an iteration limit, and when it is reached before the work is done the response comes back paused. Re-sending the conversation, including the paused response, lets Claude continue where it left off.

With the Agent SDK, the loop runs inside the library. Claude responds, the SDK runs each requested tool, the results go back to Claude, and the cycle repeats until a response contains no tool calls. Then the SDK yields a ResultMessage with the final text, token usage, cost, and session ID. Your code watches the message stream instead of building requests.

Agent frameworks such as the Claude Agent SDK, Strands Agents SDK by AWS, LangGraph, and PydanticAI take over the low-level wiring: calling the model, defining and parsing tools, and chaining calls together. Taking over that wiring is also what hides things from you. When an agent misbehaves, the cause is usually in a prompt or tool result that the framework assembled and you never saw. That makes calling the API directly the better choice in two cases: when a pattern needs only a few lines of code, and when you must inspect exactly what Claude received. If you do adopt a framework, read the code it runs underneath, and don't add steps just because the framework makes them easy to add.

Sources342

3.Subagents as a context-window strategy

The context window holds everything Claude sees in a request: the system prompt, every message, every tool result, and the tool definitions. Filling it has a cost. As token count grows, accuracy and recall degrade, which is known as context rot. In an agent loop, tool results are what fill the window fastest. Twenty file reads to find one function leave twenty files in the history for every later turn.

Subagents solve this by isolation. Each subagent runs in its own conversation, and its intermediate tool calls stay inside it. Only its final message returns to the parent. A research subagent can read dozens of files while the main conversation receives a short summary. Subagents bring three other benefits. Several can run at once, which is parallelization. Each can carry a specialised system prompt. And each can be limited to specific tools. In the Agent SDK you define them in the agents option of query(), or as markdown files in .claude/agents/. Claude can also call a built-in general-purpose subagent through the Agent tool.

"test-runner": AgentDefinition(
                    description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
                    prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
                    # Bash access lets this subagent run test commands
                    tools=["Bash", "Read", "Grep"],
                ),

Isolation is not the only tool. When a single conversation has to keep going past its limit, compaction replaces the older turns with a summary that Claude writes on the server. The broader discipline of what to keep in context belongs to [context engineering](lesson:6.1).

Sources516

4.Resuming a subagent across queries

A subagent's work is lost to you unless you capture two identifiers. Suppose an endpoint-finder subagent spends a query cataloguing every API route, and you then call query() again with a follow-up. That second call starts a fresh session with no memory of the catalogue, so the search runs again from the beginning. To continue instead, you need the session ID, which arrives on the ResultMessage. You also need the subagent's agent ID, which appears in the text of the Agent tool's result.

def extract_agent_id(block: ToolResultBlock) -> str | None:
    """Extract agentId from an Agent tool result's text content."""
    parts = block.content if isinstance(block.content, list) else [{"text": block.content}]
    for part in parts:
        if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):
            return match.group(1)
    return None

Both identifiers are needed, and each does a different job. Passing resume with the session ID gives the second query access to the earlier transcript. Putting the agent ID in the prompt tells Claude which subagent in that transcript to continue. Resuming is also how you recover from maxTurns. When a subagent hits its turn limit, its output comes back marked as partial, and resuming lets it finish with the context it already built.

Sources14

5.Memory that outlives the session

The context window is working memory, and it ends with the session. Resuming carries one transcript forward. Compaction keeps one conversation inside the window's limit. Neither one lets an agent start a new task next week already knowing what it learned this week. For that, knowledge has to leave the context window and go into storage.

The memory tool provides that storage as files. Claude can create, read, update, and delete files in a memory directory, under /memories, and those files persist between sessions. When the tool is enabled, Claude checks the directory before it starts a task. As it works, it writes down what it learns. This is just-in-time retrieval: the agent loads a memory file only when the current task needs it, instead of putting everything it has ever learned into context at the start. A research agent running across dozens of sessions keeps a small active context and still builds up a knowledge base.

The memory tool runs client-side. Claude only requests file operations. Your application performs them against storage you control and returns each result in a tool_result block, so you decide where the data lives and who can read it. Because Anthropic publishes the tool's schema, Claude has been trained on it and calls it more reliably than a homemade equivalent.

Sources735

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A complex multi-step task always calls for an autonomous agent.Why is that wrong?

   Start simple and add complexity only when it is needed. A fixed workflow, or even a single call, often wins on cost and predictability. Agents fit when the steps can't be predicted.

   Covered in The five workflow patterns and when an agent fits instead

2. 2.Server tools such as web_search need your code to execute them and return tool_result blocks.Why is that wrong?

   Anthropic runs server tools and their loop. Your code enables the tool and handles pause_turn, but never builds their results.

   Covered in Who drives the tool-use loop

3. 3.A follow-up query() automatically reaches the subagent that ran in the previous query.Why is that wrong?

   Each query() starts a new session. You must resume the earlier session by its ID and name the agent ID to continue that subagent's transcript.

   Covered in Resuming a subagent across queries

4. 4.Loading every past finding into the context at the start of each session is the right way to give an agent long-term memory.Why is that wrong?

   The memory tool keeps knowledge in files and reads them back only when needed, so the active context stays focused on the current task.

   Covered in Memory that outlives the session