零废话！一文讲透从0构建AI Agent

LLM（大语言模型）
 │
 │  厂商通过 HTTP 提供调用能力
 ▼
LLM API
 │
 │  客户端维护对话历史数组
 ▼
Context（上下文）
 │
 │  告诉 LLM "你有哪些工具可用"
 ▼
Tool Calling（工具调用）
 │
 │  加入循环：思考 → 行动 → 观察
 ▼
Agent Loop（智能体循环）
 │
 ├──────────────┬──────────────┐
 ▼              ▼              ▼
MCP 协议      Sub-Agent     Agent Skill
(标准化工具对接) (分工协作)    (流程复用)

你的代码 → HTTP POST（带上问题） → LLM 服务 → HTTP 响应（返回回答）

第 1 次请求：[消息1]                          → AI 回复1
第 2 次请求：[消息1, 回复1, 消息2]             → AI 回复2
第 3 次请求：[消息1, 回复1, 消息2, 回复2, 消息3] → AI 回复3

{ "functionCall": { "name": "get_weather", "args": { "city": "深圳" } } }

Agent = LLM（大脑） + Tools（手脚） + Loop（驱动循环）

const body = {
  messages: [
    { role: "system", content: "你是一个有帮助的助手。" },
    { role: "user", content: "你好" },
  ],
};

const res = await fetch(apiEndpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${apiKey}`,
  },
  body: JSON.stringify(body),
});

const data = await res.json();
console.log(data.choices[0].message.content);

class Chat {
  private history: Message[] = [];

  async send(text: string): Promise<string> {
    this.history.push({ role: "user", content: text });
    const reply = await this.client.sendMessage(this.history, this.systemPrompt);
    this.history.push({ role: "assistant", content: reply });
    return reply;
  }
}

{
  name: "run_shell_command",
  description: "Run a shell command on the user's machine...",
  parameters: {
    command: { type: "string", description: "The shell command to execute" },
  },
  required: ["command"],
}

execute(params: Record<string, unknown>): Promise<unknown> {
  const command = params.command as string;
  return new Promise((resolve) => {
    exec(command, { timeout: timeoutMs }, (error, stdout, stderr) => {
      resolve({ exitCode: error?.code ?? 0, stdout, stderr });
    });
  });
}

// 纯文本回复
{ "text": "你好！有什么可以帮你的？" }

// 工具调用请求
{ "functionCall": { "name": "run_shell_command", "args": { "command": "ls -la" } } }

async send(text: string): Promise<string> {
  this.history.push({ role: "user", content: text });

  for (let i = 0; i < MAX_ROUNDS; i++) {
    const result = await this.client.sendMessage(this.history, options);
    this.history.push({ role: "assistant", content: result });
    
    if (!result.functionCall) {
      return result.text ?? "";
    }
    
    const { name, args } = result.functionCall;
    const toolResult = await this.toolRegistry.execute(name, args);
    
    this.history.push({
      role: "tool",
      content: JSON.stringify({ name, result: toolResult }),
    });
 }

  throw new Error("Max tool call rounds exceeded");
}

用户："帮我看看当前目录有什么文件，然后统计代码行数"

第 1 圈：AI → 执行 ls -la → 代码返回结果
第 2 圈：AI → 执行 wc -l src/*.ts → 代码返回结果
第 3 圈：AI → 返回文本总结 → 循环结束 ✅

interface ToolExecuteResult {
  data: unknown;        // LLM 需要的结构化原始数据
  displayText?: string; // 用户在终端看到的友好提示
}

function slidingWindow(history: Message[], maxTurns: number): Message[] {
  if (history.length <= maxTurns * 2) {
    return history;
  }
  const systemPrompt = history[0];
  const recentMessages = history.slice(-(maxTurns * 2));
  return [systemPrompt, ...recentMessages];
}

原始历史（5000 tokens）：
  用户问了天气 → AI 查了天气 → 用户问了新闻 → AI 查了新闻 → ...

压缩后（200 tokens）：
  "用户先查了深圳天气（25°C 晴），然后查了今日科技新闻（共 3 条），
   接着要求将新闻翻译成英文。"

用户提问："上次讨论的数据库方案是什么？"

  1. 把问题转成向量 → 去向量数据库检索
  2. 找到相关的历史片段 → 注入当前上下文
  3. LLM 基于检索结果回答

┌─────────────────────────────────────────────┐
│ 1. 系统提示词                    (始终保留)   │
│ 2. 压缩摘要（旧历史）            (摘要压缩)    │
│ 3. 检索到的相关知识片段           (RAG)       │
│ 4. 最近 N 轮对话                 (滑动窗口)   │
│ 5. 当前用户输入                  (始终保留)   │
└─────────────────────────────────────────────┘

Agent A 对接 GitHub   → 写一套 GitHub 工具定义 + 执行逻辑
Agent A 对接 Slack    → 写一套 Slack 工具定义 + 执行逻辑
Agent B 对接 GitHub   → 再写一套（跟 A 的还不一样）
...

Agent A ─┐                  ┌─ GitHub MCP Server
Agent B ─┤── MCP 协议 ──────┤─ Slack MCP Server
Agent C ─┘   (标准接口)      └─ 数据库 MCP Server

┌─────────────────────────────────────────────────┐
│                    Host                         │
│   (Agent 应用)                                  │
│                                                 │
│   ┌────────────┐  ┌────────────┐                │
│   │ MCP Client │  │ MCP Client │  ...           │
│   └─────┬──────┘  └─────┬──────┘                │
└─────────┼───────────────┼───────────────────────┘
          │ MCP 协议       │ MCP 协议
          ▼               ▼
   ┌────────────┐  ┌────────────┐
   │ MCP Server │  │ MCP Server │
   │  (GitHub)  │  │ (Database) │
   └────────────┘  └────────────┘

Agent(Host)              MCP Client              MCP Server
    │                        │                        │
    │  1. 启动时              │   ── initialize ──▶   │
    │                        │   ◀── 工具列表 ────    │
    │                        │                        │
    │  2. 用户提问            │                        │
    │  ──"查 GitHub issue"─▶ │                        │
    │                        │                        │
    │  3. LLM 决定调工具      │                        │
    │  ── tool_call ──────▶ │   ── execute ────▶     │
    │                        │   ◀── result ─────    │
    │  ◀── tool_result ───── │                       │
    │                        │                        │
    │  4. LLM 生成回复        │                        │
    │  ◀── 返回给用户         │                        │

用户："帮我调研 React 和 Vue 的优缺点，然后写一个技术选型报告"

                    ┌──────────────┐
                    │   主 Agent   │  ← 理解任务、拆分、汇总
                    │(Orchestrator)│
                    └───────┬──────┘
                  ┌─────────┼─────────┐
                  ▼         ▼         ▼
           ┌───────────┐ ┌──────────┐ ┌──────────┐
           │调研 Agent  │ │调研 Agent│ │写作 Agent│
           │ (React)   │ │ (Vue)    │ │ (报告)   │
           └───────────┘ └──────────┘ └──────────┘

name: code-reviewer            # 唯一标识
description: "Reviews code..." # 描述信息，用于主 Agent 决策时选择
tools: [read_file, list_dir]   # 工具白名单
model: "model-name"            # 可覆盖默认模型
maxTurns: 15                   # 限制最大工具调用轮数
prompt: |                      # 专属系统提示词
  You are a code reviewer specialized in identifying:
  - Security vulnerabilities
  - Performance issues
  ...

主 Agent 决定委派任务
    │
    ▼
1. 根据任务描述选择合适的 Sub-Agent
    │
    ▼
2. 构建受限的工具集（只给白名单中的工具）
    │
    ▼
3. 创建新的 Chat 实例（独立上下文）
    │
    ▼
4. Sub-Agent 执行任务（在自己的 Agent Loop 中）
    │
    ▼
5. 返回结果给主 Agent（只有最终结果，没有中间过程）

┌─────────────────────────────────────────────────────┐
│                   Agent Skill                       │
│                                                     │
│  元数据:                                             │
│    name / description / trigger                     │
│                                                     │
│  Prompt 模板:                                       │
│    作为 prompt 注入主对话上下文                       │
│    指导 Agent 按步骤执行任务                          │
└─────────────────────────────────────────────────────┘

name: commit
description: "Generate a conventional commit message for staged changes"
trigger: /commit
prompt: |
  Analyze the staged changes and generate a commit message
  following the Conventional Commits specification.
  The commit message should:
  1. Start with a type: feat, fix, docs, style, refactor, test, or chore
  2. Include a scope in parentheses if applicable
  3. Have a concise subject line (max 50 chars)
  4. Include a body if the change is complex

const skillMatch = skillRegistry.match(userInput);
if (skillMatch) {
  const injectedPrompt = skillLoader.load(skillMatch.skill, skillMatch.args);
  const reply = await chat.send(injectedPrompt);
}

{
  "tool": "skill",
  "parameters": {
    "skill_name": "commit",
    "task": "为当前暂存的更改生成提交信息"
  }
}

需求来了
  │
  ├─ 是单个原子操作？（读文件、发请求、执行命令）
  │   └─ → 用 Tool
  │
  ├─ 是固定流程？（每次步骤一样，只是输入不同）
  │   └─ → 用 Skill
  │
  ├─ 需要独立上下文？（中间过程会污染主对话）
  │   └─ → 用 Sub-Agent
  │
  └─ 需要不同模型？（子任务适合用专门的模型）
      └─ → 用 Sub-Agent

用户输入 /review（触发 Skill）
    │
    ▼
Skill prompt 指导主 Agent 拆分任务
    │
    ├─ Sub-Agent 1：代码审查（使用 read_file Tool）
    ├─ Sub-Agent 2：安全检查（使用 grep、read_file Tool）
    └─ Sub-Agent 3：性能分析（使用 run_command Tool）
    │
    ▼
主 Agent 汇总三个 Sub-Agent 的结果，生成报告