Agent Design Patterns

Master the core design patterns that power production AI agents — from ReAct loops to multi-agent orchestration architectures.

Cognitive Architecture

An agent's cognitive architecture defines how it processes information, makes decisions, and executes tasks. The most common pattern is ReAct (Reasoning + Acting):

┌─────────────────────────────────────────────────────────┐
│                    Agent Runtime                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐            │
│   │ Observe │ → │  Think  │ → │   Act   │ ─┐          │
│   └─────────┘    └─────────┘    └─────────┘  │          │
│        ↑                                      │          │
│        └──────────────────────────────────────┘          │
│                                                          │
├─────────────────────────────────────────────────────────┤
│   Memory   │   Tools   │   Knowledge   │   Skills       │
└─────────────────────────────────────────────────────────┘

System Layers

A typical agent system can be divided into the following layers:

1. Interface Layer

Entry points for users to interact with the agent, including:

• CLI command-line interface
• Web UI / Chat interface
• API endpoints
• IDE integrations

2. Core Layer

The agent's core logic, including:

• LLM Controller - Manages interaction with the language model
• Task Manager - Task decomposition and execution management
• Context Manager - Context window management
• Decision Engine - Decision-making engine

3. Capability Layer

The agent's capability modules:

• Tools - File operations, shell commands, API calls, etc.
• Memory - Short-term memory, long-term memory, vector storage
• Skills - Reusable capability packages

4. Infrastructure Layer

• LLM providers (OpenAI, Anthropic, local)
• Vector databases
• Logging and monitoring
• Security sandbox

Common Design Patterns

ReAct Pattern

Alternating reasoning and acting is the most basic and practical pattern:

Thought: I should read the config file to understand the project structure.
Action: read_file("config.json")
Observation: {"name": "my-app", ...}
Thought: This is a Node.js project. Next...
Action: ...

Plan & Execute Pattern

Make a full plan first, then execute step by step. Best for complex tasks:

Plan:
1. Analyze requirements
2. Design the solution
3. Implement the code
4. Write tests
5. Validate results

Execute: [execute the plan step by step...]

Reflexion Pattern

Reflect after execution and learn from failures:

Execute → Observe Result → Reflect → Improve → Re-execute

Practical Example: Claude Code Architecture

Claude Code's architecture illustrates a production-grade agent design:

┌────────────────────────────────────────┐
│           Terminal Interface           │
├────────────────────────────────────────┤
│          Conversation Manager          │
├────────────────────────────────────────┤
│   System Prompt  │  Tool Definitions   │
├────────────────────────────────────────┤
│              Claude API                │
├────────────────────────────────────────┤
│ FileSystem │ Shell │ Search │ Memory  │
└────────────────────────────────────────┘

Best Practices

• Modular design - Tools, memory, and skills should be plug-and-play
• Error recovery - Agents should recover from errors and retry
• Safety boundaries - Clearly define agent permissions and limits
• Observability - Record decision processes for debugging and optimization
• Context management - Use tokens wisely and avoid limit overruns

import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "Refactor the auth module",
  options: {
    permissionMode: "plan",  // Plan before execute
    settingSources: ["project", "local"],

    hooks: {
      PreToolUse: async (input) => {
        console.log(`[PRE] ${input.toolName}`, input.toolInput);
        const start = Date.now();
        // Attach timing data for PostToolUse
        return { allow: true, metadata: { start } };
      },

      PostToolUse: async (input) => {
        const duration = Date.now() - input.metadata?.start;
        console.log(`[POST] ${input.toolName} took ${duration}ms`);
        await logToDatabase({
          tool: input.toolName,
          duration,
          success: !input.result?.isError
        });
      },

      Stop: async (input) => {
        console.log("[STOP] Agent finished, cleaning up...");
        // Final logging, resource cleanup
      }
    }
  }
});

Next Steps

Explore the components of agent architecture in more detail:

• LLM & Prompts - How the agent's "brain" works
• Tools & Actions - How agents interact with the outside world
• Memory Systems - How agents remember and learn