AI Agent Development in Practice: Architecture Design and Implementation Guide

At 3 AM, I stared at the terminal where an Agent task had been running for twenty minutes—it was stuck in an infinite loop, repeatedly calling the same tool, like a drunk person trapped in a dead end.

This wasn’t my first time hitting this wall. Over the past two years of Agent development, I’ve seen too many similar crashes: ReAct Agents mysteriously falling into infinite loops, multi-agent systems turning into endless debate conferences, Plan-and-Execute patterns being helpless with dynamic tasks.

Honestly, when you first encounter terms like ReAct, Plan-and-Execute, and Multi-Agent, you’ll likely be confused—which one to choose? What’s the difference? When should you use a single agent, and when must you go multi-agent?

This article aims to lay out all the experience and pitfalls I’ve encountered over the years. We’ll discuss:

• Three levels of Agent architecture, and why “use simple solutions when possible”
• Three core patterns—ReAct, Plan-and-Execute, and Multi-Agent—their principles and code implementations
• Five multi-agent orchestration patterns: Sequential, Concurrent, Group Chat, Handoff, and Magentic
• How to choose between LangChain, AutoGen, CrewAI, and Claude Agent SDK
• Build a working Agent with Claude Agent SDK

Let’s dive in.

One, Three Levels of Agent Architecture

Let’s start with a principle many beginners overlook: if a simple solution works, don’t add complex architecture.

Azure officially divides Agent architecture into three levels, and this classification is particularly practical:

1.1 Direct Model Call

The simplest level. You throw a task at the model, and it gives you an answer directly.

// Most basic invocation
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Help me summarize this text...' }]
});

Suitable scenarios: single-step tasks, highly deterministic scenarios, scenarios that don’t need external tools. Such as text summarization, translation, code completion.

Advantages? Simple, cheap, controllable. Disadvantages? Cannot handle complex tasks requiring multi-step reasoning, cannot call external tools.

1.2 Single Agent with Tools

This is the default choice for most enterprise scenarios. The Agent can call tools and handle multi-step tasks.

// LangChain single agent example
import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

// Define a weather query tool
const weatherTool = tool(
  async ({ city }) => {
    // Simulate weather API call
    return `${city} is sunny today, temperature 22°C`;
  },
  {
    name: 'get_weather',
    description: 'Get weather information for a specified city',
    schema: z.object({
      city: z.string().describe('City name'),
    }),
  }
);

const model = new ChatAnthropic({
  model: 'claude-sonnet-4-20250514',
  temperature: 0,
});

const agent = await createToolCallingAgent({
  llm: model,
  tools: [weatherTool],
  prompt: 'You are a helpful assistant.',
});

const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool],
});

// Run
const result = await executor.invoke({
  input: 'How is the weather in Beijing today?',
});

Suitable scenarios: scenarios requiring tool calls, decomposable tasks, relatively fixed steps. Such as data analysis, code execution, API orchestration.

1.3 Multi-Agent Orchestration

The most complex level. Multiple specialized Agents each handle their own responsibilities, collaborating to complete tasks.

To be honest, there are fewer scenarios that genuinely need this level than you might think. Introducing multi-agent means coordination overhead, state management complexity, and debugging difficulty all increase exponentially.

Suitable scenarios: cross-domain complex tasks, requiring specialized division of labor, scenarios where a single Agent cannot cope. Such as software development pipelines (requirements analysis → design → coding → testing), complex decision-making systems.

1.4 How to Choose? A Decision Table

One-sentence summary: Start simple, add what you need.

Two, Three Core Architecture Patterns Explained

After determining which level to use, the next step is choosing a pattern. These three patterns are not mutually exclusive—in many scenarios, they’ll be combined.

2.1 ReAct (Reasoning-Acting) Pattern

ReAct is short for Reasoning + Acting, the core idea is to let the model “think while doing”.

Working Principle:

User Input → Thought → Action → Observation → Loop or End

For example, user asks “Is the weather in Beijing tomorrow suitable for outdoor sports?”:

1. Thought: I need to check Beijing’s weather for tomorrow
2. Action: Call get_weather tool with parameter city: "Beijing"
3. Observation: Beijing tomorrow will be cloudy, temperature 18-25°C, precipitation probability 10%
4. Thought: Temperature is moderate, precipitation probability is low, suitable for outdoor sports
5. Final Answer: Beijing tomorrow is suitable for outdoor sports, suggest wearing a light jacket

Code Implementation (LangChain):

import { ChatAnthropic } from '@langchain/anthropic';
import { AgentExecutor, createReactAgent } from 'langchain/agents';
import { pull } from 'langchain/hub';

// ReAct prompt template
const prompt = await pull('hwchase17/react');

const agent = await createReactAgent({
  llm: model,
  tools: [weatherTool, searchTool], // Your tool list
  prompt,
});

// Set maximum iterations to prevent infinite loops!
const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools: [weatherTool, searchTool],
  maxIterations: 10, // Important: prevent infinite loops
  verbose: true, // Print reasoning process, essential for debugging
});

Pros and Cons Analysis:

Pitfall Warning: Always set maxIterations, otherwise when encountering tasks that can’t be completed, the Agent will keep running—my first ReAct Agent ran all night like this.

2.2 Plan-and-Execute Pattern

ReAct’s problem is it “takes one step at a time”, easily going off track with complex tasks. Plan-and-Execute’s approach: first make a plan, then execute step by step.

Working Principle:

User Input → Planner generates plan → Executor executes step by step → Return result

Code Implementation (LangGraph):

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

import { ChatAnthropic } from '@langchain/anthropic';
import { StateGraph, END } from '@langchain/langgraph';

// Define state structure
interface AgentState {
  input: string;
  plan: string[];
  pastSteps: string[];
  response: string;
}

// Planning node: generate execution plan
async function planNode(state: AgentState): Promise<AgentState> {
  const plannerPrompt = `Given user goal: ${state.input}
Please generate a detailed execution plan, one step per string, return in JSON array format.`;

  const response = await model.invoke(plannerPrompt);
  const plan = JSON.parse(response.content as string);
  return { ...state, plan };
}

// Execution node: execute one step of the plan
async function executeNode(state: AgentState): Promise<AgentState> {
  const currentStep = state.plan[0];
  const result = await executor.invoke({ input: currentStep });

  return {
    ...state,
    plan: state.plan.slice(1), // Remove completed step
    pastSteps: [...state.pastSteps, `${currentStep}: ${result.output}`],
  };
}

// Build graph
const workflow = new StateGraph<AgentState>({
  channels: {
    input: { value: null },
    plan: { value: null },
    pastSteps: { value: null, default: () => [] },
    response: { value: null },
  },
});

workflow.addNode('planner', planNode);
workflow.addNode('executor', executeNode);

// Define edges: execute after planning
workflow.addEdge('planner', 'executor');

// Conditional edges: check if steps remain
workflow.addConditionalEdges('executor', (state) => {
  return state.plan.length > 0 ? 'executor' : END;
});

Pros and Cons Analysis:

My Experience: Plan-and-Execute is particularly suitable for tasks with “predictable steps”, such as batch data processing, report generation. But for tasks requiring frequent strategy adjustments, ReAct is actually more suitable.

2.3 Multi-Agent Pattern

When tasks are complex enough that a single Agent can’t handle them, it’s time to bring in multi-agent.

Core Idea: Each Agent focuses on one domain, collaborating like a team.

Code Implementation (Claude Agent SDK style):

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

// Create specialized agents
const researchAgent = new ClaudeAgent({
  name: 'researcher',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'You are a research expert, responsible for collecting and organizing information.',
  tools: ['WebSearch', 'WebFetch'],
});

const writerAgent = new ClaudeAgent({
  name: 'writer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'You are a content creation expert, responsible for writing and polishing articles.',
  tools: ['Read', 'Write', 'Edit'],
});

const reviewerAgent = new ClaudeAgent({
  name: 'reviewer',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'You are a quality review expert, responsible for checking content accuracy and readability.',
  tools: ['Read'],
});

// Collaboration process
async function collaborativeWriting(topic: string) {
  // Step 1: Research
  const research = await researchAgent.run(`Research topic: ${topic}`);

  // Step 2: Writing
  const draft = await writerAgent.run(
    `Based on the following research results, write an article:\n${research}`
  );

  // Step 3: Review
  const review = await reviewerAgent.run(
    `Review the following article and provide revision suggestions:\n${draft}`
  );

  // Step 4: Revision
  const final = await writerAgent.run(
    `Revise the article based on review feedback:\nOriginal: ${draft}\nFeedback: ${review}`
  );

  return final;
}

When to Use Multi-Agent:

• Tasks require multiple professional skills (e.g., programming + design + copywriting)
• Single Agent context window is insufficient
• Need specialized division of labor, each handling their own domain

Warning: Multi-agent debugging difficulty increases exponentially. State synchronization, message passing, and error handling between two Agents all become complex. If a single agent can solve it, don’t force multi-agent.

Three, Five Multi-Agent Orchestration Patterns

If your scenario genuinely needs multi-agent, the next step is choosing an orchestration pattern. These five patterns summarized by Azure cover most scenarios.

3.1 Sequential Orchestration

The most intuitive pattern: Agent A’s output is Agent B’s input, like a pipeline.

[Agent A] → [Agent B] → [Agent C] → Final Result

Suitable Scenarios: Document generation pipelines (research → draft → review → publish), code generation processes.

Code Example:

// Sequential orchestration example
async function sequentialPipeline(input: string) {
  const step1 = await researchAgent.run(input);
  const step2 = await writerAgent.run(step1.output);
  const step3 = await editorAgent.run(step2.output);
  return step3.output;
}

Note: Output format of each step must be agreed upon in advance, otherwise downstream Agents will receive data they can’t understand.

3.2 Concurrent Orchestration

Multiple Agents process the same input simultaneously, then aggregate results.

           → [Agent A] →
[Input]  →  → [Agent B] →  → [Aggregator] → Final Result
           → [Agent C] →

Suitable Scenarios: Multi-perspective analysis, stock evaluation (technical + fundamental + news analysis in parallel), code review (security + performance + style checks in parallel).

Code Example:

// Concurrent orchestration example
async function concurrentAnalysis(code: string) {
  const [security, performance, style] = await Promise.all([
    securityAgent.run(`Security review:\n${code}`),
    performanceAgent.run(`Performance analysis:\n${code}`),
    styleAgent.run(`Code style check:\n${code}`),
  ]);

  // Aggregate results
  return {
    security: security.output,
    performance: performance.output,
    style: style.output,
  };
}

Note: Parallel execution requires attention to result aggregation logic—different Agents may have conflicting suggestions, requiring an arbitration mechanism.

3.3 Group Chat Orchestration

Multiple Agents discuss in a “chat room” until reaching consensus or timeout.

[Agent A] ⇄ [Agent B] ⇄ [Agent C]
     ↑           ↓
   [Moderator]

Suitable Scenarios: Brainstorming, quality validation, scenarios requiring multiple rounds of discussion to make decisions.

Azure Official Suggestion: Limit group chat agents to 3 or fewer. More than that becomes a debate conference.

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

Code Example:

// Group chat orchestration example (pseudocode illustration)
interface ChatMessage {
  sender: string;
  content: string;
}

async function groupChatDiscussion(
  topic: string,
  agents: ClaudeAgent[],
  maxRounds: number = 5
) {
  const history: ChatMessage[] = [];

  for (let round = 0; round < maxRounds; round++) {
    for (const agent of agents) {
      const response = await agent.run(
        `Discussion topic: ${topic}\nCurrent conversation history: ${JSON.stringify(history)}\nPlease share your perspective.`
      );
      history.push({ sender: agent.name, content: response.output });

      // Check if consensus reached
      if (checkConsensus(history)) {
        return summarizeConsensus(history);
      }
    }
  }

  return 'Discussion timed out, no consensus reached';
}

Pitfall Experience: Always set maxRounds, otherwise two stubborn Agents can argue indefinitely. Also, it’s best to have a Moderator role responsible for converging the discussion.

3.4 Handoff Orchestration

One Agent completes a task, then hands off work to the next Agent.

[Agent A] detects need for B's expertise → Handoff to [Agent B] → Continue processing

Suitable Scenarios: Customer service bots (pre-sales → technical support → after-sales), troubleshooting (diagnosis → repair → verification).

Code Example:

// Handoff orchestration example
const supportAgent = new ClaudeAgent({
  name: 'support',
  systemPrompt: `You are customer support. If user asks technical questions, reply "HANDOFF:tech".
If user asks after-sales questions, reply "HANDOFF:after_sales".`,
});

const techAgent = new ClaudeAgent({
  name: 'tech',
  systemPrompt: 'You are a technical support expert.',
});

async function handleWithHandoff(userInput: string) {
  let currentAgent = supportAgent;
  let response = await currentAgent.run(userInput);

  // Detect handoff signal
  while (response.output.includes('HANDOFF:')) {
    const targetAgent = response.output.match(/HANDOFF:(\w+)/)?.[1];

    if (targetAgent === 'tech') currentAgent = techAgent;
    else if (targetAgent === 'after_sales') currentAgent = afterSalesAgent;

    response = await currentAgent.run(userInput);
  }

  return response.output;
}

Note: Handoff logic must be clear, avoid circular handoffs (A hands to B, B hands back to A).

3.5 Magentic Orchestration

The most flexible pattern: based on task nature, dynamically “attract” the most suitable Agent to handle it.

[Task Pool] → [Intelligent Scheduler] → Based on task characteristics select [Agent A/B/C]

Suitable Scenarios: Systems with diverse task types, scenarios requiring dynamic resource scheduling.

Implementation Approach:

// Magentic orchestration example
interface Task {
  type: string;
  priority: number;
  content: string;
}

async function magenticScheduling(task: Task) {
  // Based on task type, select most suitable Agent
  const agentScores = await Promise.all(
    agents.map(async (agent) => {
      const score = await evaluateAgentFit(agent, task);
      return { agent, score };
    })
  );

  // Select highest-scoring Agent
  const bestAgent = agentScores.sort((a, b) => b.score - a.score)[0].agent;
  return bestAgent.run(task.content);
}

Note: Need to design good “fit evaluation” logic, otherwise scheduling becomes random assignment.

3.6 Pattern Selection Quick Reference

Four, Mainstream Framework Comparison and Selection

After discussing architecture patterns, it’s time to talk about which specific framework to use. This area is indeed dizzying—LangChain, AutoGen, CrewAI, Claude Agent SDK, each has their own story.

First, my viewpoint: there’s no best framework, only the framework most suitable for your scenario.

4.1 Framework Positioning Comparison

4.2 Detailed Framework Features

LangChain: The veteran, most mature ecosystem.

• Full support for both TypeScript and Python
• Built-in extensive tools and integrations
• Ready-made implementations for ReAct, Plan-and-Execute
• Downside? API changes frequently, documentation sometimes can’t keep up

AutoGen: Microsoft product, first choice for multi-agent collaboration.

• Core concept is “conversation”, Agents collaborate through message passing
• Supports human-in-the-loop
• Suitable for scenarios requiring multiple rounds of discussion and decision-making
• Downside? Steep learning curve, debugging multi-agent systems is painful

CrewAI: The newcomer, focuses on simplicity.

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

• Models using “roles”, “tasks”, “teams” concepts, very intuitive
• Clean API design, quick to get started
• Suitable for quickly building multi-agent prototypes
• Downside? Ecosystem and tool integration not as rich as LangChain

Claude Agent SDK: Anthropic official product, new tool released in 2026.

• Deep integration with Claude models
• Built-in file read/write, code editing, command execution capabilities
• Supports permissionMode to control operation permissions
• If your primary model is Claude, this is the first choice

4.3 Selection Decision Guide

Ask yourself a few questions:

1. What’s your primary model?

   • Claude → Prioritize Claude Agent SDK
   • OpenAI → LangChain ecosystem more mature
   • Multi-model → LangChain or AutoGen

2. How complex is the task?

   • Single Agent + tools → LangChain sufficient
   • Multi-Agent collaboration → AutoGen or CrewAI
   • Code-related tasks → Claude Agent SDK

3. What’s your team’s tech stack?

   • Primarily Python → All frameworks supported
   • Primarily TypeScript → LangChain, Claude Agent SDK have better support

4. Do you need human-machine collaboration?

   • Need → AutoGen’s human-in-the-loop is well designed
   • Don’t need → Other frameworks work fine

4.4 My Selection Recommendation

Honestly, for most scenarios, LangChain is sufficient. Its tool integration and ReAct implementation are both mature, with good community support.

If you’re certain you need multi-agent, and the task is genuinely complex enough to require multiple specialized Agents collaborating, AutoGen is worth trying. But remember: multi-agent debugging cost is high, don’t do it just for “technical advancement”.

If you’re a heavy Claude user, Claude Agent SDK is currently the best choice—after all, it’s officially produced, with the best coordination with Claude models.

Five, Practice - Building an Agent with Claude Agent SDK

After all this theory, let’s get practical. Use Claude Agent SDK to write a working code refactoring Agent.

5.1 Environment Setup

# Install dependencies
npm install @anthropic-ai/claude-agent-sdk

# Set API Key
export ANTHROPIC_API_KEY=your_api_key_here

5.2 Basic Agent Example

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

// Create a code refactoring Agent
const refactorAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'acceptEdits', // Automatically accept edit operations
  workingDirectory: './src', // Working directory
});

// Execute task
async function refactorCode(task: string) {
  const result = await refactorAgent.run(task);
  console.log('Refactoring result:', result);
  return result;
}

// Usage example
refactorCode('Refactor auth.ts file, convert callback-style code to async/await');

5.3 Important Configuration Explained

permissionMode (Permission Mode):

• 'acceptEdits': Automatically accept file edit operations
• 'interactive': Each operation requires manual confirmation
• 'planOnly': Only generate plan, don’t execute

tools (Available Tools):

• Read: Read files
• Write: Create new files
• Edit: Edit existing files
• Bash: Execute command line commands
• Glob: File pattern matching
• Grep: Content search

5.4 More Complex Example: Agent with Constraints

const cautiousAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit', 'Bash'],
  permissionMode: 'interactive', // Cautious mode: requires manual confirmation
  maxIterations: 20, // Limit maximum iterations
  timeout: 300000, // 5 minute timeout

  // System prompt: define Agent behavior boundaries
  systemPrompt: `You are a code refactoring expert.
Rules:
1. Do not delete any test files
2. Do not modify package.json
3. Backup original files before each modification
4. Run tests after modification to ensure functionality works`,
});

async function safeRefactor(filePath: string) {
  try {
    const result = await cautiousAgent.run(
      `Please refactor ${filePath}, optimize code structure and readability.`
    );
    return result;
  } catch (error) {
    console.error('Refactoring failed:', error);
    // Rollback logic...
  }
}

5.5 Best Practices

1. Limit iteration count: Prevent Agent from falling into infinite loops
2. Set timeout: Long-running tasks need a fallback
3. Permission levels: Use interactive mode for sensitive operations
4. Backup mechanism: Backup important files before modification
5. Test verification: Run tests after modification, ensure functionality works

5.6 Debugging Tips

// Enable detailed logging
const debugAgent = new ClaudeAgent({
  model: 'claude-sonnet-4-20250514',
  tools: ['Read', 'Write', 'Edit'],
  verbose: true, // Print detailed execution process
});

// Listen to events
debugAgent.on('toolCall', (tool, args) => {
  console.log(`Calling tool: ${tool}, parameters: ${JSON.stringify(args)}`);
});

debugAgent.on('thinking', (thought) => {
  console.log(`Agent thinking: ${thought}`);
});

Wrapping Up

After all this discussion, the core idea of Agent architecture selection comes down to one sentence: Start simple, add what you need.

First, judge your task complexity:

• Single-step task? Call model directly
• Need tools? Single agent + tools
• Genuinely need multiple specialized roles? Then consider multi-agent

Then choose a pattern:

• Task changes dynamically? ReAct
• Steps predictable? Plan-and-Execute
• Need specialized division of labor? Multi-Agent

Finally choose a framework:

• Claude user? Claude Agent SDK
• Multi-model, multi-tool? LangChain
• Multi-agent collaboration? AutoGen or CrewAI

After all this talk, the most important thing is to get hands-on. Find a small project, build an Agent and run it—step into a few pitfalls, and you’ll understand.

Questions welcome in the comments, or check out my previous two articles: “MCP Server Development Getting Started” and “Agent Tool Calling in Practice”—these three articles are part of a continuous series.

12 min read · Published on: Mar 21, 2026 · Modified on: Mar 22, 2026

Easton

AI & Intelligence