从零实现一个轻量级AI Agent：工具调用与任务编排实践

CodeConductor

407人浏览 · 2026-06-12 16:56:32

CodeConductor · 2026-06-12 16:56:32 发布

阅读前置：本文面向后端/前端/AI应用开发工程师，无需深度学习算法基础，基于TypeScript从零实现极简Agent，弄懂LLM智能体底层逻辑，告别只会调用对话接口的浅层开发。

技术栈：TypeScript、OpenAI Function Calling、原生异步调度、JSON Schema工具标准化

落地成果：核心代码放到文章最后

一、引言：为什么你需要理解Agent

1.1 行业演进：从对话LLM到功能性Agent

2023年至今大语言模型落地分为两个阶段：

1.0对话阶段：LLM核心能力是文本生成、问答、文案改写，交互形态局限于「人机对话」，输入文字、返回文字，无法联动外部系统、操作系统、业务接口，本质是被动文本应答工具。
2.0智能体阶段：Agent在LLM基础上补齐外部联动能力，具备自主理解、自主决策、自主调用工具、自主修正流程的能力，不再单纯做文字聊天，而是主动完成业务任务。

简单总结：LLM是会说话的大脑，Agent是会干活的完整个体。

1.2 当下LLM落地核心痛点

绝大多数企业LLM项目卡在同一个问题：大模型只会空想，不会动手。

用户问今日气温，LLM无法实时调用天气API，只能回答历史知识库数据；
用户指令发送工作邮件，LLM无法对接邮箱服务完成投递；
运维场景查询代码合并记录、推送告警消息，纯对话模型完全无法适配；
自定义业务接口无法被模型识别调用，业务价值极低。

核心矛盾：原生LLM是离线静态模型，无法对接外部世界、无法执行操作，而业务需要模型闭环完成「理解-做事-反馈」全流程。

1.3 本文核心目标

避开市面框架封装黑盒（LangChain、Dify二次封装），纯原生手写一款极简微型Agent，完整实现行业标准的感知-规划-执行闭环能力：

感知：接收用户自然语言指令，读取上下文记忆信息；
规划：LLM自主拆解任务、选择适配工具、编排执行步骤；
执行：调用第三方API/业务工具，获取结果并回写上下文；
闭环：循环推理，直至任务完成，输出最终业务结果。

文末附带可直接复制运行的TS源码、业务运维实战案例、单Agent瓶颈优化方案，看完即可改造适配自身业务。

二、核心架构设计：读懂Agent底层骨架

2.1 微型Agent三大核心组件（缺一不可）

所有开源Agent、企业级智能体，底层都由三大模块构成，类比人体结构极易理解：

2.1.1 LLM：智能体大脑（决策核心）

负责语义理解、意图判断、任务拆分、参数生成、结果总结、异常纠错。不负责接口调用、IO操作、数据查询，只做决策与推理。兼容GPT系列、通义千问、DeepSeek等具备Function Calling能力的主流模型。

2.1.2 工具集：智能体双手（执行核心）

所有外部可调用能力统称工具：接口API、文件读写、命令行、机器人推送、数据库查询、Git操作都属于工具。工具统一标准化定义，交由LLM自主选择调用，开发无需硬编码判断用户指令。

2.1.3 记忆模块：智能体记忆（上下文核心）

分为两级存储，适配不同任务场景：

短期记忆：内存级上下文，存储本轮任务对话、工具入参、执行结果，支撑ReAct循环推理，任务结束可销毁；
长期记忆：磁盘/数据库持久化，存储用户偏好、历史任务、工具权限、业务规则，赋能跨会话自主决策。

2.2 主流任务编排模式对比

Agent自主干活的核心逻辑，依靠任务编排模式驱动，本文核心采用工程落地最优解：ReAct循环模式。

2.2.1 思维链CoT（Chain of Thought）

仅做文本分步推理，无工具调用能力，适合数学解题、文案分步撰写，无法联动外部接口，仅纯文本推理场景使用，业务Agent基本淘汰该模式。

2.2.2 ReAct模式（Reason + Act 推理执行循环）

当下业务Agent标准编排模式，闭环流程：

接收指令→LLM推理是否需要调用工具→调用工具执行→获取结果写入上下文→再次推理是否需要二次调用工具→任务完结输出结果

优势：自主循环、自主纠错、适配多步骤复合任务，本次运维案例完全基于ReAct开发。

2.3 技术选型说明

备选方案：Python（生态丰富，适合AI算法快速开发）
本文选型：TypeScript（适配前端/Node全业务、对接企业钉钉/Git/内部中台接口更便捷、异步IO适配工具调度、可直接部署服务）

核心依赖：原生Node.js Http能力+模型Function Calling能力，零重型框架依赖，轻量化易改造。

三、关键实现细节：可复刻底层代码逻辑

3.1 工具标准化：JSON Schema定义与动态注册

LLM不会自动识别工具用法，必须遵循JSON Schema规范标准化描述工具功能、入参、参数类型、必填项，模型才能自主生成合法调用参数，这是Agent工具调用的核心前提。

3.1.1 工具标准结构

每一个工具固定包含：工具名称、功能描述、入参Schema、执行回调函数四大字段，支持全局动态注册、卸载、权限管控。

// 标准化工具TS类型定义
interface AgentTool {
  name: string; // 工具唯一标识，模型调用标识
  description: string; // 自然语言描述：告诉模型什么时候用这个工具
  parameters: JSONSchema7; // 入参校验Schema
  handler: (params: Record<string,any>) => Promise<string>; // 工具执行逻辑
}
// 全局工具注册表
const toolRegistry = new Map<string, AgentTool>()
// 工具注册方法
function registerTool(tool: AgentTool){
  toolRegistry.set(tool.name, tool)
}

3.1.2 实操工具注册示例（Git查询PR工具）

精准撰写description决定模型是否会正确选用工具，文案必须直白贴合用户业务话术。

3.2 规划器核心实现：基于Function Calling做意图解析

规划器是Agent大脑调度器，核心依托LLM原生Function Calling能力，完成三件事：

拼接用户指令+历史记忆+全局工具列表，封装prompt入参模型；
接收模型返回结果，区分「直接回答文本」和「工具调用指令」；
解析工具名称、入参，下发给执行器调度。

规避自研意图识别算法：依托模型原生能力，无需训练分类模型，适配自定义业务话术，开发成本极低。

3.3 ReAct异步执行与上下文闭环

完整ReAct闭环执行流程：

感知层：读取用户prompt + 短期记忆上下文；
规划层：规划器判断调用工具，生成调用参数；
执行层：异步执行对应工具handler，捕获接口异常；
回写层：工具执行结果、报错信息全部写入短期记忆；
循环层：再次调用LLM，判断是否需要新增工具调用，直至任务完成。

3.4 生产级安全边界设计（上线必加）

原生ReAct极易出现死循环、越权调用工具，生产环境必须配置三重防护规则：

最大循环次数限制：单任务最大ReAct轮次限制为5轮，超出直接终止任务，避免模型无限推理调用工具耗尽接口额度；
敏感操作二次确认：删除代码分支、群发全员通知、数据库修改类高危工具，必须返回人工确认弹窗，模型无法自主执行；
入参黑白名校验：拦截非法IP、高危文件路径、超大入参，防止注入攻击。

四、案例实战：运维专属Agent——前端仓库PR巡检+钉钉群通知

4.1 业务场景

用户自然语言指令：昨天前端仓库有哪些PR？帮我通知到运维工作群里

业务痛点：以往运维每日手动登录Git仓库筛选日期、复制PR标题、编辑消息、粘贴钉钉发送，每日重复耗时8-10分钟，Agent全自动闭环完成。

预置工具：①Git代码仓库PR查询工具 ②钉钉机器人消息推送工具

4.2 四步ReAct完整执行链路

Step1：意图识别（LLM规划）

模型解析用户双重意图：1.筛选昨日前端仓库已创建PR 2.汇总信息推送钉钉群；判定需要先后调用git_query_pr、dingtalk_send_msg两个工具，编排执行顺序。

Step2：调用Git第三方API

自动填充入参：仓库标识=frontend-web、筛选时间=昨日00:00-24:00，调用仓库接口，获取PR提交人、合并状态、PR标题、关联分支原始数据。

Step3：LLM摘要精简

过滤无效字段，精简原始接口数据，生成适配钉钉阅读的结构化文案，剔除代码哈希、冗余参数等无关信息。

Step4：调用钉钉机器人推送

携带群Webhook密钥、消息markdown格式参数，调用推送工具，完成群消息投递，任务终止。

4.3 实战性能数据

总ReAct推理轮次：2轮
模型推理耗时：1120ms
双工具接口执行耗时：1560ms
全链路总耗时：2680ms ＜ 3s

4.4 核心运行问题复盘

1. 初始版本模型颠倒调用顺序：先发消息再查PR，通过优化工具description业务优先级解决；

2. 历史PR数据过多超长：新增工具入参limit条数限制，约束返回数据体量。

五、延伸思考：从单Agent到Multi-Agent企业协作

5.1 本文单Agent核心局限性

循环陷阱问题：复杂多分支任务，单Agent自我纠错能力弱，极易陷入重复调用同一个工具的死循环；
权责耦合严重：同一个LLM既要做规划、又要做执行校验、结果评估，精力拆分不足，复杂任务准确率大幅下降；
工具权限不可拆分：所有工具共用一套权限，无法精细化管控读写、推送高危操作。

5.2 下一代Multi-Agent分工协作架构

拆解单体能力，拆分角色化智能体，各司其职，企业复杂业务标准架构：

规划Agent：专职任务拆解、流程编排、难度评估，下发子任务；
执行Agent：专职调用工具、对接外部接口、完成IO操作；
评估Agent：校验执行结果、判断任务是否达标、出错回溯重执行。

5.3 行业标准化方向：MCP模型上下文协议

当下痛点：各家Agent工具格式、上下文格式、调用协议不统一，自研Agent无法互通LangChain、Dify、企业自研平台智能体。

MCP（Model Context Protocol）最新行业协议价值：统一工具定义、统一上下文传输、统一多智能体通信标准，未来无需适配格式，不同团队开发的Agent可直接互联互通，是2026下半年企业Agent基建核心方向。

六、核心代码

// Agent主循环核心骨架（基于openai协议的tool_calls实现）
const MAX_STEPS = 15;  // 最大循环步数上限

async function agentTurn(messages, opts) {
  const tools = getTools();  // 工具定义列表，包含name/description/parameters schema
  for (let step = 0; step < MAX_STEPS; step++) {
    // 1) 调用LLM，传入对话历史 + 工具定义，让模型决定下一步
    const llmResult = await callLLM(messages, tools, opts);
    const msg = llmResult.message;
    messages.push(msg);  // 将助手回复存入对话历史

    // 2) 模型回复中没有tool_calls → 说明已给出最终答案，结束本轮
    if (!msg.tool_calls || msg.tool_calls.length === 0) {
      return msg.content;  // 终止Agent循环
    }

    // 3) 有tool_calls → 执行工具，把执行结果塞回消息历史，然后继续下一轮
    for (const toolCall of msg.tool_calls) {
      const result = await executeTool(toolCall);  // 调用外部工具/API
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(result)
      });
    }
    // 循环继续，模型拿到工具结果后会再次推理
  }
  console.log("已达到最大步数限制");
}