AI Agent 开发实战指南：从零构建智能代理系统

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// 传统 Chatbot：单轮对话
interface Chatbot {
  query: (message: string) => Promise<string>;
}

// AI Agent：多步推理与行动
interface Agent {
  observe: () => Promise<Observation>;
  reason: (obs: Observation) => Promise<Thought>;
  act: (thought: Thought) => Promise<Action>;
  reflect: () => Promise<void>;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

interface ReActAgent {
  async run(task: string): Promise<Result> {
    let thought = this.initialThought(task);
    const steps: Step[] = [];

    while (!thought.isComplete()) {
      // 推理阶段
      const reasoning = await this.reason(thought);

      // 行动阶段
      const action = await this.decideAction(reasoning);
      const observation = await this.executeAction(action);

      // 记录步骤
      steps.push({ reasoning, action, observation });

      // 更新思考
      thought = await this.updateThought(thought, observation);
    }

    return this.compileResult(steps);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// 工具定义
interface Tool {
  name: string;
  description: string;
  parameters: z.Schema;
  execute: (params: unknown) => Promise<ToolResult>;
}

// 工具注册表
class ToolRegistry {
  private tools = new Map<string, Tool>();

  register(tool: Tool) {
    this.tools.set(tool.name, tool);
  }

  getToolDescription(): string {
    return Array.from(this.tools.values())
      .map(t => `- ${t.name}: ${t.description}`)
      .join('\n');
  }

  async callTool(name: string, params: unknown): Promise<ToolResult> {
    const tool = this.tools.get(name);
    if (!tool) {
      throw new Error(`Tool not found: ${name}`);
    }

    // 参数验证
    const validated = tool.parameters.parse(params);
    return tool.execute(validated);
  }
}

// 实用工具示例
const searchTool: Tool = {
  name: 'web_search',
  description: '在互联网上搜索信息',
  parameters: z.object({
    query: z.string().describe('搜索关键词'),
    num_results: z.number().default(5).describe('返回结果数量')
  }),
  execute: async ({ query, num_results }) => {
    const results = await searchEngine.search(query, { num_results });
    return { success: true, data: results };
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// 多层级记忆架构
interface MemorySystem {
  // 工作记忆：当前上下文
  workingMemory: WorkingMemory;

  // 短期记忆：会话历史
  shortTermMemory: ShortTermMemory;

  // 长期记忆：向量数据库
  longTermMemory: LongTermMemory;
}

// 向量记忆实现
class VectorMemory {
  private embeddingModel: EmbeddingModel;
  private vectorDB: VectorDatabase;

  async store(memory: Memory): Promise<void> {
    const embedding = await this.embeddingModel.encode(memory.content);
    await this.vectorDB.insert({
      id: memory.id,
      vector: embedding,
      metadata: memory.metadata,
      timestamp: Date.now()
    });
  }

  async retrieve(query: string, topK: number = 5): Promise<Memory[]> {
    const queryEmbedding = await this.embeddingModel.encode(query);
    const results = await this.vectorDB.similaritySearch(queryEmbedding, topK);

    return results.map(r => ({
      id: r.id,
      content: r.metadata.content,
      relevance: r.score,
      metadata: r.metadata
    }));
  }

  async searchByTimeRange(
    start: Date,
    end: Date,
    filters?: Record<string, unknown>
  ): Promise<Memory[]> {
    return this.vectorDB.filter({
      timestamp: { $gte: start.getTime(), $lte: end.getTime() },
      ...filters
    });
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

// 管理者 Agent
class ManagerAgent {
  private subAgents: Map<string, Agent>;

  async execute(task: ComplexTask): Promise<Result> {
    // 任务分解
    const subtasks = await this.decomposeTask(task);

    // 分配给子 Agent
    const promises = subtasks.map(async (subtask) => {
      const agent = this.selectAgent(subtask);
      return agent.execute(subtask);
    });

    // 等待所有子任务完成
    const results = await Promise.all(promises);

    // 整合结果
    return this.integrateResults(results);
  }
}

// 专家 Agent 示例
class CodeAgent extends BaseAgent {
  tools = [this.writeCode, this.debugCode, this.refactorCode];

  systemPrompt = `你是一个编程专家，擅长：
  - 编写高质量代码
  - 调试和修复bug
  - 代码重构和优化`;

  async execute(task: CodingTask): Promise<CodeResult> {
    // 分析需求
    const analysis = await this.analyzeRequirements(task);

    // 编写代码
    const code = await this.writeCode(analysis);

    // 测试验证
    const tests = await this.generateTests(code);
    const testResults = await this.runTests(tests);

    if (!testResults.allPassed) {
      return this.fixBugs(code, testResults.failures);
    }

    return { code, tests, status: 'success' };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// Agent 通信协议
interface AgentMessage {
  from: string;
  to: string;
  type: 'request' | 'response' | 'notify';
  content: unknown;
  timestamp: number;
}

// 协商式任务分配
class NegotiationOrchestrator {
  private agents: Agent[];

  async distributeTask(task: Task): Promise<TaskAssignment> {
    // 向所有 Agent 发送任务提案
    const proposals = await Promise.all(
      this.agents.map(async (agent) => {
        const confidence = await agent.evaluateTask(task);
        return { agent, confidence, estimate: agent.estimateTime(task) };
      })
    );

    // 选择最佳 Agent
    const sorted = proposals.sort((a, b) => {
      // 综合考虑置信度和时间估算
      const scoreA = a.confidence * 0.7 - a.estimate * 0.3;
      const scoreB = b.confidence * 0.7 - b.estimate * 0.3;
      return scoreB - scoreA;
    });

    const selected = sorted[0];
    return {
      agent: selected.agent,
      task,
      deadline: Date.now() + selected.estimate * 1.2
    };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

class ResearchAssistant extends BaseAgent {
  tools = [
    searchTool,
    paperDatabaseTool,
    summarizationTool,
    citationTool
  ];

  async researchTopic(topic: string): Promise<ResearchReport> {
    const report: ResearchReport = {
      topic,
      sections: [],
      references: []
    };

    // 1. 搜索相关文献
    const searchResults = await this.callTool('web_search', {
      query: `${topic} latest research 2026`,
      num_results: 10
    });

    // 2. 阅读和分析论文
    for (const result of searchResults.data) {
      const summary = await this.callTool('summarize_paper', {
        url: result.url,
        focus: topic
      });

      report.sections.push({
        title: result.title,
        content: summary.content,
        keyFindings: summary.keyFindings
      });

      report.references.push({
        title: result.title,
        authors: result.authors,
        url: result.url,
        year: result.year
      });
    }

    // 3. 生成综合报告
    report.synthesis = await this.generateSynthesis(report.sections);

    return report;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

class CodeReviewAgent extends BaseAgent {
  async reviewCode(diff: CodeDiff): Promise<ReviewResult> {
    const issues: Issue[] = [];

    // 1. 静态分析
    const staticIssues = await this.staticAnalysis(diff);
    issues.push(...staticIssues);

    // 2. 安全检查
    const securityIssues = await this.securityCheck(diff);
    issues.push(...securityIssues);

    // 3. 最佳实践检查
    const practiceIssues = await this.bestPracticeCheck(diff);
    issues.push(...practiceIssues);

    // 4. 性能分析
    const performanceIssues = await this.performanceAnalysis(diff);
    issues.push(...performanceIssues);

    // 5. 生成审查报告
    return {
      overallScore: this.calculateScore(issues),
      issues: issues.sort((a, b) => b.severity - a.severity),
      suggestions: await this.generateSuggestions(issues),
      approval: this.shouldApprove(issues)
    };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

interface AgentMetrics {
  // 任务成功率
  successRate: number;

  // 平均完成任务时间
  avgCompletionTime: number;

  // 工具调用准确率
  toolAccuracy: number;

  // 推理质量（人工评估）
  reasoningQuality: number;

  // 资源消耗
  tokenUsage: number;
  apiCallsCost: number;

  // 用户满意度
  userSatisfaction: number;
}

// 评估框架
class AgentEvaluator {
  async evaluate(agent: Agent, testSuite: TestCase[]): Promise<AgentMetrics> {
    const results = await Promise.all(
      testSuite.map(test => agent.run(test.task))
    );

    return {
      successRate: this.calculateSuccessRate(results),
      avgCompletionTime: this.calculateAvgTime(results),
      toolAccuracy: this.calculateToolAccuracy(results),
      reasoningQuality: await this.evaluateReasoning(results),
      tokenUsage: this.calculateTokenUsage(results),
      apiCallsCost: this.calculateCost(results),
      userSatisfaction: await this.surveyUsers(results)
    };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// 使用少样本学习
const systemPrompt = `
你是一个专业的代码助手。以下是几个例子：

示例1：
用户：帮我写一个快速排序
助手：[展示优质代码和解释]

示例2：
用户：这个函数有bug
助手：[定位问题，解释原因，提供修复方案]

现在请处理用户的请求。
`;

// 思维链提示
const cotPrompt = `
让我们一步步思考这个问题：
1. 首先，分析用户的需求...
2. 然后，确定需要的步骤...
3. 最后，执行并验证...
`;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// 动态记忆管理
class AdaptiveMemory {
  async prioritizeMemories(): Promise<void> {
    const memories = await this.getAllMemories();

    // 计算记忆重要性分数
    const scored = memories.map(memory => ({
      ...memory,
      score: this.calculateImportance(memory)
    }));

    // 保留高价值记忆
    const retained = scored
      .filter(m => m.score > this.threshold)
      .sort((a, b) => b.score - a.score)
      .slice(0, this.maxMemories);

    await this.updateMemories(retained);
  }

  calculateImportance(memory: Memory): number {
    // 最近性权重
    const recency = Math.exp(-(Date.now() - memory.timestamp) / 86400000);

    // 访问频率权重
    const frequency = memory.accessCount / this.totalAccesses;

    // 内容相关性权重
    const relevance = this.semanticRelevance(memory);

    return recency * 0.3 + frequency * 0.3 + relevance * 0.4;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// 事实验证机制
class FactChecker {
  async verify(agentResponse: string): Promise<VerificationResult> {
    // 提取关键事实声明
    const claims = await this.extractClaims(agentResponse);

    const results = await Promise.all(
      claims.map(async (claim) => {
        // 多源验证
        const verifications = await Promise.all([
          this.searchEngine.verify(claim),
          this.knowledgeBase.check(claim),
          this.database.query(claim)
        ]);

        // 综合判断
        const confidence = this.aggregateConfidence(verifications);

        return {
          claim,
          isFactual: confidence > 0.8,
          confidence,
          sources: verifications.flatMap(v => v.sources)
        };
      })
    );

    return {
      allClaimsFactual: results.every(r => r.isFactual),
      questionableClaims: results.filter(r => !r.isFactual),
      verifications: results
    };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Token 使用优化
class TokenOptimizer {
  async optimizeAgentRun(agent: Agent, task: string): Promise<Result> {
    // 1. 使用缓存
    const cached = await this.cache.get(task);
    if (cached && this.isCacheValid(cached)) {
      return cached.result;
    }

    // 2. 选择合适模型
    const complexity = this.estimateComplexity(task);
    const model = this.selectModel(complexity);

    // 3. 压缩上下文
    const compressedContext = await this.compressContext(task, model);

    // 4. 执行并缓存结果
    const result = await agent.runWithModel(compressedContext, model);
    await this.cache.set(task, { result, timestamp: Date.now() });

    return result;
  }

  selectModel(complexity: number): LLMModel {
    if (complexity < 0.3) {
      return this.lightweightModel; // 更快更便宜
    } else if (complexity < 0.7) {
      return this.standardModel;
    } else {
      return this.advancedModel; // 最强能力
    }
  }
}

1
2
3
4
5
6
7
8

# LangChain 快速开始
npm install @langchain/core @langchain/openai

# 本地向量数据库
npm install @chromadb/core

# Agent 测试框架
npm install @agent-ui/test-utils