1. 项目背景与需求分析
最近我在为公司的奥德赛研发平台(一个基于TQL的BFF接口开发平台)接入了Agent开发能力。这个想法源于我在使用Cursor、Claude Code等AI编程工具时的体验——它们极大地提升了我的前端开发效率。于是我开始思考:如何让后端开发团队也能享受到AI辅助编程的红利?
奥德赛平台目前的工作方式是:开发者编写TQL脚本来实现BFF接口。TQL是淘宝基于GraphQL定制的一种查询语言,而ICBU又在TQL基础上做了进一步定制。这种层层定制导致了一个核心问题:公开的大语言模型(如Claude、Qwen等)根本不了解这些私有的语法规范。
2. 技术方案选型
2.1 现有平台架构分析
原平台的架构相对简单:开发者在一个Web IDE中编写TQL脚本,可以进行编码、调试和发布。界面主要包含:
- 代码编辑器区域
- 参数输入面板
- 执行结果展示区
- 调试工具集
2.2 Agent集成方案对比
在现有平台中集成Agent,需要考虑如何让Agent感知页面环境并进行操作。我们评估了三种主流方案:
-
浏览器插件方案:
- 优点:可以深度操作页面元素
- 缺点:需要用户安装插件,跨平台兼容性差
-
DevTools协议方案:
- 优点:可以完全控制页面
- 缺点:需要额外服务,安全性风险高
-
iframe嵌入方案:
- 优点:无缝集成,安全性高
- 缺点:功能受iframe沙箱限制
经过综合评估,我们选择了第三种iframe嵌入方案,主要基于以下考虑:
- 用户体验一致性
- 开发维护成本
- 安全性要求
2.3 数据流转设计
在iframe方案中,数据流转是关键。我们的设计如下:
-
宿主页面暴露:
- 上下文信息:脚本内容、请求参数、调试结果等
- 操作接口:脚本执行、Diff预览等
-
Agent功能:
- 感知页面上下文
- 调用服务端能力
- 推送编辑、执行等操作指令
3. 技术栈选型
3.1 后端服务:FaaS平台
选择集团内部的FaaS平台主要基于以下考虑:
- 全托管服务,免运维
- 弹性伸缩,适合Agent的间歇性负载
- 与现有技术栈无缝集成
FaaS平台让我们只需关注业务逻辑代码,无需操心服务器运维、资源扩缩容等基础设施问题。
3.2 前端框架:Next.js + React
选择这个组合的原因包括:
- 集团有成熟的一体化框架支持
- 前后端使用相同语言(JavaScript),AI辅助编码效率高
- 完善的生态系统和社区支持
3.3 Agent框架:LangGraph
LangGraph是LangChain团队推出的Agent开发框架,其核心优势在于:
- 状态图(state graph)抽象
- 清晰的节点和边定义
- 灵活的条件路由
通过LangGraph,我们可以用伪代码这样定义一个基础Agent:
javascript复制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.addConditionalEdges(
'agent',
(state) => {
const lastMsg = state.messages[state.messages.length - 1];
return lastMsg.tool_calls?.length > 0 ? 'tools' : END;
},
{ tools: 'tools', [END]: END }
);
4. 核心实现细节
4.1 提示词工程优化
由于模型不了解TQL这种私有语法,提示词设计尤为关键。我们采用了Anthropic推荐的优化技巧:
4.1.1 角色设定
使用XML格式明确Agent的角色和能力边界:
xml复制<role>
你是小D同学,一个专业的TQL脚本编写助手,TQL是淘宝基于GraphQL扩展的查询语言,
你只会写TQL语法,不会任何其它脚本。你的任务是帮助用户基于企业知识和用户输入,
编写高质量的TQL脚本。
</role>
4.1.2 指令设计
通过instructions引导模型行为:
xml复制<instructions>
<instruction>你非常欠缺TQL知识,但好在系统内置了很多工具</instruction>
<instruction>遇到不确定需求时,必须用工具查询相关知识</instruction>
<instruction>回答要专业、友好、有条理。使用Markdown格式输出。</instruction>
</instructions>
4.1.3 示例引导
针对常见问题提供正例引导:
xml复制<rule>
<title>参数分离原则</title>
<content>
建议将GraphQL请求的参数单独放在variables中。
示例:
脚本:query($userId: String!) { user(id: $userId) { name } }
参数:{"userId": "12345"}
</content>
</rule>
4.2 知识库建设
由于TQL的私有性,我们构建了三类知识库:
-
线上热门脚本:
- 采集top 100调用量的脚本
- 使用Qwen模型生成解释文档
- 每个脚本独立存储,优化RAG召回效果
-
系统内置字段:
- 扫描出全局指令、函数和领域模型
- 与线上脚本匹配,保留高频使用部分
- 废弃内容清理和相似内容合并
-
服务端代码理解:
- 利用内部code search工具
- 集成deepwiki的代码理解能力
- 建立从字段到实现的映射关系
4.3 工具系统设计
工具分为本地工具和远程工具两类:
4.3.1 远程工具(MCP)
-
知识库查询工具:
- 接口:/kbase/query
- 参数:query(查询内容), top_k(返回条数)
- 返回:相关知识片段
-
代码理解工具:
- 接口:/deepwiki/search
- 参数:code_snippet(代码片段)
- 返回:代码解释和关联信息
4.3.2 本地工具
-
脚本编辑工具:
- 功能:更新GraphQL脚本
- 参数:script(完整脚本内容)
- 返回:操作状态
-
变量编辑工具:
- 功能:更新请求变量
- 参数:variables(JSON字符串)
- 返回:操作状态
-
执行验证工具:
- 功能:验证脚本结果
- 参数:prompt(验证要求)
- 返回:验证结果和建议
4.4 上下文管理
4.4.1 连续对话实现
- 为每个会话创建唯一sessionId
- 使用Tair持久化存储消息历史
- 新请求时加载历史消息,保持上下文连贯
4.4.2 UI工具调用机制
由于FaaS不支持长连接,我们设计了特殊的工作流:
- 服务端使用SSE(Server-Sent Events)推送消息
- 遇到UI工具调用时,终止当前请求
- 前端处理完UI操作后,以"隐藏消息"形式发起新请求
- 服务端从检查点恢复处理
4.4.3 上下文压缩
为避免token超限,实现了两种压缩策略:
- 工具结果压缩:
- 缓存工具原始响应
- 使用轻量模型(Qwen)提取关键信息
- 结构化输出节省token
xml复制<field>
<name>freight</name>
<type>复合类型</type>
<description>物流模型</description>
<arguments>
<arg required="false">
<name>dispatchCountryCode</name>
<type>String</type>
</arg>
</arguments>
</field>
- 对话历史压缩:
- 当token使用超过80%时触发
- 保留最近3轮完整对话
- 压缩早期历史为摘要
5. 经验总结与避坑指南
5.1 提示词优化心得
- 角色设定要具体:明确限制Agent的能力范围,避免"万能助手"幻觉
- 指令要可操作:避免模糊要求,给出明确的行为指引
- 示例要给正例:反例可能误导模型注意力
- 格式要用XML:显著提升指令遵循率
5.2 工具设计要点
- 功能要单一:每个工具只做一件事
- 接口要稳定:避免频繁变更影响Agent行为
- 文档要详细:包括参数说明和示例
- 要有白名单:只暴露必要的工具
5.3 性能优化技巧
- 工具结果缓存:避免重复调用
- 轻量模型辅助:用Qwen处理结构化提取
- 动态知识加载:仅当需要时查询相关知识
- 上下文窗口监控:实时计算token消耗
5.4 常见问题排查
-
模型不遵循指令:
- 检查提示词格式(推荐使用XML)
- 增加角色设定的约束力
- 降低temperature参数
-
工具调用失败:
- 验证工具接口可用性
- 检查参数格式是否符合预期
- 查看模型对工具的理解是否准确
-
上下文丢失:
- 检查session存储机制
- 验证消息持久化流程
- 监控token使用情况
6. 效果评估与改进方向
6.1 当前效果
经过优化后,Agent表现出以下能力:
- 能够编写符合规范的TQL脚本
- 可以正确使用私有指令和函数
- 能够自主调试和修正脚本错误
- 可以基于知识库回答专业问题
6.2 量化指标
- 脚本一次通过率:从人工的60%提升到85%
- 开发时间节省:平均每个接口节省2小时
- 知识查询准确率:达到92%
- 平均响应时间:1.5秒内
6.3 未来优化方向
- 多Agent协作:引入专业Agent分工合作
- 工作流优化:支持更复杂的开发场景
- 模型微调:针对TQL进行专项优化
- 自动化测试:集成测试验证能力
通过这个项目,我们验证了Agent技术在专业领域的应用潜力。关键是要处理好专业知识的获取和应用,以及设计良好的交互机制。希望这个实践案例能给想要自建Agent的开发者提供有价值的参考。