自建一个 Agent 很难吗?一语道破,万语难明

最近花了一周左右的时间给内部的一个传统研发平台接入了 Agent 开发的能力,很多同学对 Agent 的底层实现非常感兴趣,所以此篇给大家介绍下我是怎么做的,希望能对想自建 Agent 的同学有所启发。

因人力原因,有些细节方案问题没太做深度评测,而是直接选择业界实践较多的成熟方案。主要参考思路和上下文管理的过程。


文中用到了一些内部平台的基础能力,比如 rag、代码管理、deepwiki等,外部开发者如需使用需要自行寻找替代品。

背景简介

奥德赛研发平台是 ICBU 买家技术的 TQL(淘宝基于开源 GraphQL 的定制版本) 研发平台,大量开发者会在上面通过编写 TQL 脚本来实现 BFF 接口。

近一年 AI Coding 工具层出不穷,在深度使用了 cursor、claude code 等顶尖产品后,大量解放了自己在前端的生产力,所以就在想让团队的后端兄弟(还有姐妹)们也吃好点,告别纯手搓代码,这不,BFF 的 Agent 模式(小 D 同学)来了~

技术选型

原来的平台长这样,开发者在上面可以完成编码、调试、发布等工作:

要在现有的平台内集成一个 Agent ,且能感知前台页面的环境,甚至对页面进行操作,一般有三种方式(默认都采用 AI 辅助 Coding):

如果只是一般的对话 Agent,直接用一些开放的应用平台搭建就完事了,不必自己写。

综合考量了三种方案后,我们决定优先保证用户体验&开发效率,选择了第三种。

宿主页面 Iframe 嵌入 Agent

整体的数据流转概要:

1. 宿主页面暴露 脚本内容、请求参数、调试结果 等上下文信息,以及脚本执行、脚本 Diff 预览等操作页面的工具接口给 Agent。
2. Agent 感知宿主页面上下文环境,然后请求服务,并推送内容编辑、脚本执行等工具执行 action 给宿主页面。

流程概要图如下:

应用框架选择

应用框架选择上不做过多对比,直接给出我的选择,不一定最好,但是一定很契合我当前的场景。

集团 Faas 基建

简介:FaaS(Function as a Service,函数即服务)平台是一个面向研发人员的全托管、事件驱动、弹性伸缩的 Serverless 计算基础设施,其核心目标是让开发者只关注业务逻辑代码本身,无需操心服务器运维、资源扩缩容、中间件对接等底层细节。

划重点,Faas 可以让你只关注代码,免运维。这正是当前这种轻量 Agent 需要的。

Next.js + React

前后端应用框架我选择了 Next.js + React,为什么?

1. 集团有前后端一体化的框架可以直接用。
2. 前后端共用一套开发语言(Nodejs、JavaScript),并集成在一个应用中,AI Coding 非常友好,谁用谁知道。可以真正做到只关注功能,AI 帮你做实现。

LangGraph

LangChain [1]团队在 WorkFlow/Agent 领域摸爬滚打了几年,高度抽象了 Agent 的开发模式。

LangGraph 其巧妙设计让你可轻松构建一个状态图,你可以只关注 系统提示词、工具节点(通常是 MCP)就可轻松实现一个会自主决策的 Agent。手残党友好。

方案落地

应用框架初始化

如上文所述,结合当前场景,把 LangGraph 抽象出来的状态图展开,替换成自己的工具,就得到这样一个图和伪代码:

此处了解个大概就可以了,稍后会详解工具

BFF Agent 状态图:

伪代码:

import { StateGraph, END, START } from '@langchain/langgraph';
// 创建状态图const agentGraph = new StateGraph({  channels: {    messages: {      reducer: (prev, next) => [...prev, ...next],      default: () => [],    },  },});
// 添加节点agentGraph.addNode('agent', async (state) => {  const response = await model.invoke(state.messages);  return { messages: [response] };});
agentGraph.addNode('tools', async (state) => {  const lastMsg = state.messages[state.messages.length - 1] as AIMessage;  const toolMessages = [];  for (const toolCall of lastMsg.tool_calls || []) {    const result = await tools      .find((t) => t.name === toolCall.name)      .invoke(toolCall.args);    toolMessages.push(      new ToolMessage({ content: result, tool_call_id: toolCall.id }),    );  }  return { messages: toolMessages };});
// 设置边agentGraph.addEdge(START, 'agent');agentGraph.addEdge('tools', 'agent');
// 条件边:根据是否有 tool_calls 决定路由agentGraph.addConditionalEdges(  'agent',  (state) => {    const lastMsg = state.messages[state.messages.length - 1] as AIMessage;    return lastMsg.tool_calls?.length > 0 ? 'tools' : END;  },  { tools: 'tools', [END]: END },);
// 编译图const graph = agentGraph.compile();

参考 LangGraph 的官方文档的介绍,用 Cursor 可以轻松实现上述一个基础的有向、有环状态图,至此,BFF Agent 服务的基础骨架就好了。模型选择上,由于需要生码,我还是直接使用了 Claude (Claude-4.5-haiku)的模型。

那么接下来的重点就是从能用到好用,后续的内容非常关键。也就是上下文工程的优化,接下来的优化是不分顺序的,因为上下文工程是一个综合命题,比如你往往需要在系统提示词优化完成后,发现某些工具调用不符合预期,又回过头来优化系统提示词。不同类型的上下文往往是交叉影响的,要根据具体场景做甄别。

系统提示词优化

Anthropic 官方推荐了提示词优化[2]的诸多技巧,非常有效!下面介绍我高频用到的几个基础技巧,更多技巧真的强烈建议直接学习原文。

1. 角色设定

角色设定可以显著提高模型的性能(参考Qwen 的 MOE 机制),并改进模型的注意力,发现更多的关键问题。

2. 使用 XML 

Anthropic 官方推荐使用 XML 构建提示词[3],有诸多好处,实测非常有效。遇到模型不遵循指令,或上下文过长,出现遗忘/幻觉时,试试更换提示词格式为 XML。

3. 使用示例

也就是 few-shot ,给少量准确的示例,尤其对输出内容改善上有重大帮助。还有,一篇 research [4]有介绍,尽量直接给模型正例而不是反例,保护模型的注意力。(比如我告诉你不要去想一会要吃什么,你反而会刻意去想如何不要去想这件事情,就浪费了你的注意力)

上述三个技巧是非常简单且行之有效的方法,全程指导了我去优化提示词,来看具体怎么用的 👇

角色设定 & 使用 XML

淘宝的 TQL 本质上是一种 GraphQL 的方言,ICBU 还又在 TQL 的基础上做了定制,大模型是不可能会写的:

模型不了解私域知识这个问题,在自建 Agent 的时候往往是一个共性问题,所以才需要大量的提示词 & 工具 & 知识库。强如 Claude ,公司自己的 Qwen ,都不知道 TQL 的含义。

好在,模型不用从 0 开始,它会写 GraphQL,那么只需要阐述清楚二者的区别。不只是提示词,后续的知识库也是尽力在给模型解释私域知识。小 D 的提示词摘要:

<role>你是小 D 同学,一个专业的 TQL 脚本编写助手,TQL 是淘宝基于 GraphQL 扩展的查询语言,你只会写 TQL 语法,不会任何其它脚本。你的任务是帮助用户基于企业知识和用户输入,编写高质量的 TQL 脚本。</role><instructions>  <instruction>你非常欠缺 TQL 知识,但好在系统内置了很多工具,你可以充分使用这些工具来辅助你完成任务。</instruction>  <instruction>系统在开源 GraphQL 的基础上,扩展了很多自定义的指令,如果你遇到不确定或无法实现的需求,可充分用工具查询相关知识</instruction>  <instruction>回答要专业、友好、有条理。使用 Markdown 格式输出。</instruction>  <instruction>在编写 TQL 脚本时,要确保语法正确、查询结构清晰、字段选择合理。</instruction></instructions>
  • 角色设定上,让模型更多关注 GraphQL 方向的知识,并且申明 TQL 和 GraphQL 是有区别的,让模型谨慎操作。
  • instructions(命令)上,第一条命令比较有意思,在没有这条命令之前,模型会过于自信(即便已经是最严谨状态 temperature=0),拿到用户需求后,直接开始上手写 GraphQL ,出现了与 TQL 非常不相符的代码。用第一条指令弱化了模型的信心,模型才开始谨慎地调用知识库了解更多上下文信息。

TQL 在 GraphQL 的扩展内容部分,为了防止提示词内容爆炸,我做了一轮精简,只保留基础介绍部分(索引知识),放在提示词中,并引导模型在使用到具体能力的时候,动态通过工具查询具体知识,从而保护了模型的注意力。

自定义指令:

<directives>    非常重要!系统有大量的扩展指令,具体用法需要通过工具查询相关知识,    在使用这些指令时,一定要先学习指令的用法,不要盲目使用。
    指令一般紧挨着字段或函数, fieldA @指令名 或 funcA(xx) @指令名 这样使用。        以下是常用指令(格式: "指令名":"描述|参数"):                                                                <![CDATA[{      "转换类":{"unwrap":"解包/对象拍平/对象解构","toBool":"转布尔|not","encode":"编码|protocol=http","wrap":"包装","toInt":"转整数|offset","toUpperCase":"转大写","decode":"解码|protocol=http","autoflat":"自动扁平化"},      "字符串操作":{"suffix":"添加后缀|value","prefix":"添加前缀|value"},      "条件过滤":{"hide":"隐藏字段","filterBy":"表达式过滤|spel,aviator","include":"条件包含|if!","skip":"条件跳过|if!","default":"默认值|value"},      "列表操作":{"index":"取元素|offset","ascBy":"升序|path"},      "逻辑脚本":{"mapping":"映射|func","const":"常量|value,beforeExecute=false"},      "高级扩展":{"medusa":"Medusa服务|url,language","diamond":"Diamond服务|url"}    }]]>  </directives>

全局函数:

<TQLFunctions name="系统内置的全局函数">    <description>以下是 TQL 脚本中可直接使用的内置函数,详细用法请通过知识库查询。</description>    <![CDATA[    【字符串处理】    - QL_concat: 拼接三个字符串(a, b, c参数)    - QL_string_replace: 字符串替换(replaceText, searchString, replaceString)    - QL_stringToList: 字符串按分隔符转列表(data, delimiter)    - QL_stringToJSON: 字符串转JSON对象    - QL_jsonStringify: JSON对象转字符串    - QL_joinStringByPath: 通过JSON Path提取属性并拼接(object, path, delimiter)    - QL_urlDecode: URL解码    - QL_addHttpsSchema: 自动添加或转换为https协议头    - QL_addUrlParam: 给URL添加参数(url, param)
    【数值计算】    - QL_sumLong: 两数相加(addition1, addition2)    - QL_subtraction: 两数相减(minuend, subtrahend)    - QL_divideInt: 整数除法向下取整(dividend, divisor)    - QL_random_int: 生…
— 以上为试看内容(约 40%),开通会员后阅读全文 —