FEL 智能体(Agent)开发指南:基于 FIT 函数构建工具调用型 AI 助手
FEL 智能体(Agent)开发指南:基于 FIT 函数构建工具调用型 AI 助手
导读
本指南聚焦 ModelEngine 项目 FEL(Fel Expression Language / 大模型编程框架)Java 生态中的智能体(Agent)能力,以“天气助手”为例,完整演示如何把 FIT 函数声明为 LLM 可调用的工具(Tool Use),并用 FEL 提供的默认智能体(DefaultAgent)完成“模型发起工具调用 → 执行工具 → 回填结果 → 再次推理”的闭环调度。读完本文,你将掌握 @ToolMethod 工具注解、tool-maven-plugin 编译打包、ToolRepository/ToolExecuteService 服务装配,以及如何将 Agent 以 delegate 方式嵌入 AiProcessFlow 对话流程,并理解其底层循环调度的实现原理。
Agentic AI:从 4 种设计模式到工程落地
2024 年 Snowflake 峰会开发者日上,吴恩达发表了题为“AI 代理工作流及其推动 AI 进展的潜力”的演讲,指出 Agent 工作流可能是比下一代基础模型更具潜力的 AI 发展方向。一个常被引用的对比是:零样本(Zero-shot)模式下 GPT-4 在 HumanEval(代码生成测评数据集)上的准确率约为 67.0%,而经过 Agent 加持的 GPT-3.5 准确率可达到 95.1%——这一数据说明,让模型“先思考、再行动、再修正”的 Agent 化改造能带来显著效果提升。
目前业界主要存在 4 种 Agent 设计模式:
- Reflection:让 Agent 审视和修正自己生成的输出;
- Tool Use:LLM 生成代码、调用 API 等进行实际操作;
- Planning:让 Agent 分解复杂任务并按计划执行;
- Multiagent Collaboration:多个 Agent 扮演不同角色合作完成任务。
其中应用最多的是 Tool Use 和 Multiagent Collaboration。FEL 针对工具调用和多智能体提出了针对性的解决方案,可以轻松实现工具调用的多智能体互通——每个 Agent 都是一个可独立委托(delegate)的流程单元,多个 Agent 之间可以共享工具仓库(ToolRepository)与工具执行服务(ToolExecuteService),这正是多智能体协作的基石。
实战:构建一个支持工具调用的天气助手
本示例将创建一个天气助手,并定义两个 FIT 函数 get_current_temperature 和 get_rain_probability 作为助手可以调用的工具。完整工程位于 examples/fel-example/06-agent,下面的步骤与仓库中的示例源码一一对应。
第 1 步:引入依赖与编译插件
在项目 pom.xml 中加入以下依赖:
<dependencies>
<dependency>
<groupId>org.fitframework</groupId>
<artifactId>fit-starter</artifactId>
<version>${fit.version}</version>
</dependency>
<dependency>
<groupId>org.fitframework</groupId>
<artifactId>fit-plugins-starter-web</artifactId>
<version>${fit.version}</version>
</dependency>
<dependency>
<groupId>org.fitframework.plugin</groupId>
<artifactId>fit-http-client-okhttp</artifactId>
<version>${fit.version}</version>
</dependency>
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-core</artifactId>
<version>${fel.version}</version>
</dependency>
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-flow</artifactId>
<version>${fel.version}</version>
</dependency>
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-model-openai-plugin</artifactId>
<version>${fel.version}</version>
</dependency>
<!-- 工具自动发现服务 -->
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-tool-discoverer</artifactId>
<version>${fel.version}</version>
</dependency>
<!-- 工具执行服务 -->
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-tool-executor</artifactId>
<version>${fel.version}</version>
</dependency>
<!-- Fit 工具工厂 -->
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-tool-factory-repository</artifactId>
<version>${fel.version}</version>
</dependency>
<!-- 工具工厂存储 -->
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-tool-factory-repository</artifactId>
<version>${fel.version}</version>
</dependency>
<!-- 工具存储 -->
<dependency>
<groupId>org.fitframework.fel</groupId>
<artifactId>fel-tool-repository-simple</artifactId>
<version>${fel.version}</version>
</dependency>
</dependencies>
说明:原文档中“工具工厂”一项的 artifactId 为
fel-tool-factory-fit,仓库当前实际提供的是fel-tool-factory-repository(对应 framework/fel/java/plugins/tool-factory-repository),示例工程 examples/fel-example/06-agent/pom.xml 亦采用该写法,请以仓库实际坐标为准。
同时需要配置 tool-maven-plugin,它负责在编译阶段扫描 @ToolMethod 注解的方法,把工具元数据生成到 tools.json 清单文件中(清单文件名常量定义见 ToolSchema.java):
<plugins>
<!-- 工具编译插件 -->
<plugin>
<groupId>org.fitframework.fel</groupId>
<artifactId>tool-maven-plugin</artifactId>
<version>${fel.version}</version>
<executions>
<execution>
<id>build-tool</id>
<goals>
<goal>build-tool</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
第 2 步:配置模型连接
在 application.yml 配置文件中加入以下配置(${...} 为环境变量占位,实际运行时通过环境变量注入):
fel:
openai:
api-base: '${api-base}'
api-key: '${your-api-key}'
example:
model: '${model-name}'
其中 example.model 会在控制器中通过 @Value("${example.model}") 注入,用于指定实际调用的模型名称(例如 gpt-4o、deepseek-chat 等),fel.openai.api-base 与 fel.openai.api-key 则由 fel-model-openai-plugin 读取,负责建立与 OpenAI 兼容接口的大模型服务的连接。
第 3 步:定义工具
定义天气相关的工具服务接口,通过 FIT 的 @Genericable 将方法注册为可被远程或本地调用的服务:
public interface WeatherService {
@Genericable("modelengine.example.weather.temperature")
String getCurrentTemperature(String location, String unit);
@Genericable("modelengine.example.weather.rain")
String getRainProbability(String location);
}
service 实现层使用 @Component 注册为 FIT Bean,并通过 @ToolMethod 声明工具元数据(命名空间、工具名、描述),通过 @Property 声明参数信息:
@Component
public class WeatherServiceImpl implements WeatherService {
@Override
@Fitable("default")
@ToolMethod(namespace = "example", name = "get_current_temperature", description = "获取指定城市的当前温度")
public String getCurrentTemperature(@Property(description = "城市名称", required = true) String location,
@Property(description = "使用的温度单位,可选:Celsius,Fahrenheit", defaultValue = "Celsius") String unit) {
return "26";
}
@Override
@Fitable("default")
@ToolMethod(namespace = "example", name = "get_rain_probability", description = "获取指定城市下雨的概率")
public String getRainProbability(@Property(description = "城市名称", required = true) String location) {
return "0.06";
}
}
这里出现的注解与 FIT/FEL 的对应关系如下:
@ToolMethod:工具方法注解,位于 ToolMethod.java,核心属性包括:namespace:工具命名空间,工具名在命名空间内必须唯一,默认值为"Common";name:工具名(必填),即 LLM 在函数调用中看到的函数名;description:工具描述(默认空字符串),会被写入工具 Schema 提供给模型;extraParams:额外参数名数组;returnConverter:输出转换器的方法名;extensions:扩展属性数组(@Attribute)。
@Property:FIT 框架的参数描述注解,用于描述参数含义、是否必填(required)与默认值(defaultValue),这些信息会转化为工具 Schema 中的parameters、required、default等字段(字段键名定义见 ToolSchema.java)。@Fitable:FIT 的可信(泛化)实现注解,示例中使用"default"表示默认实现。@Genericable:FIT 的服务化接口注解,让工具方法具备“面向接口的远程和本地方法调用”能力。
第 4 步:使用默认 Agent 进行调度
控制器通过构造器注入 ChatModel、ToolExecuteService、ToolRepository 与模型名配置,创建 DefaultAgent 并将其作为流程节点委托(delegate)进 AiProcessFlow:
@RequestMapping("/ai/example")
public class AgentExampleController {
private final AiProcessFlow<String, ChatMessage> agentFlow;
private final ChatOption chatOption;
private final ToolRepository toolRepository;
public AgentExampleController(ChatModel chatModel, ToolExecuteService toolExecuteService,
ToolRepository toolRepository, @Value("${example.model}") String modelName) {
this.toolRepository = toolRepository;
this.chatOption = ChatOption.custom().model(modelName).stream(false).build();
DefaultAgent agent =
new DefaultAgent(new ChatFlowModel(chatModel, this.chatOption), "example", toolExecuteService);
this.agentFlow = AiFlows.<String>create()
.map(query -> Tip.fromArray(query))
.prompt(Prompts.human("{{0}}"))
.delegate(agent)
.close();
}
@GetMapping("/chat")
public ChatMessage chat(@RequestParam("query") String query) {
List<ToolInfo> toolInfos = asParent(toolRepository.listTool("example"));
return this.agentFlow.converse()
.bind(ChatOption.custom(this.chatOption).tools(toolInfos).build())
.offer(query)
.await();
}
}
关键点拆解:
new DefaultAgent(new ChatFlowModel(chatModel, chatOption), "example", toolExecuteService):第二个参数"example"是 Agent 绑定的工具命名空间,执行工具时只会在该命名空间下查找;.delegate(agent):将 Agent 作为一个“可委托的模式单元”接入流程,AbstractFlowPattern负责把外部会话状态透传给被委托的流程(见 AbstractFlowPattern.java);toolRepository.listTool("example"):从工具仓库拉取example命名空间下的全部工具信息,并通过ChatOption.tools(...)在本次对话中绑定给模型,使模型知晓可调用的工具集合;ChatFlowModel负责把ChatOption(含动态绑定的tools)透传给底层ChatModel进行推理,见 ChatFlowModel.java。
第 5 步:验证运行效果
启动入口为 DemoApplication.java,其中调用 FitStarter.start(DemoApplication.class, args) 启动 FIT 运行时。启动后,在浏览器栏输入:
http://localhost:8080/ai/example/chat?query=北京下雨的概率是多少
返回结果示例:
{
"content": "北京下雨的概率是6%。",
"toolCalls": []
}
可以看到,大模型识别出问题需要调用 get_rain_probability 工具,发起工具调用,得到工具返回的 0.06 后,将其转化为自然语言回答“北京下雨的概率是6%”。最终返回的 toolCalls 为空数组,说明该轮对话的调用链已经收敛(模型已完成工具结果回填后的最终回答)。
源码级原理:Agent 的“推理-调用-回填”循环如何运转
工具从哪来:发现、存储与执行
从代码结构看,FEL 的工具体系由三层服务协作完成:
- 发现层:
fel-tool-discoverer中的 DefaultToolDiscoverer.java 实现了 FIT 的PluginStartedObserver/PluginStoppingObserver。当插件启动时,它会扫描插件资源中的tools.json清单(该清单正是tool-maven-plugin在编译期生成的),反序列化出ToolGroupEntity→ToolEntity,并逐个注册进ToolRepository;插件停止时则批量删除对应工具。 - 存储层:
ToolRepository接口(ToolRepository.java)提供addTool、deleteTool、getTool、listTool(namespace)四个能力,接口方法均标注了@Genericable(id = "modelengine.fel.tool.*"),意味着工具仓库本身也是一个可远程调用的 FIT 服务——这是多智能体、多进程共享工具注册中心的基础。 - 执行层:
ToolExecuteService接口(ToolExecuteService.java)提供按namespace + toolName + JSON 参数执行工具的多种重载形式,同样全部标注@Genericable,返回执行结果的字符串形式。
ToolInfo(ToolInfo.java)封装了暴露给模型的工具视图:namespace、name、description、parameters、extensions,并提供 identify(namespace, name) 生成 "namespace:name" 形式的工具唯一标识。
Agent 的循环调度流程
DefaultAgent(DefaultAgent.java)继承自 AbstractAgent(AbstractAgent.java),后者用 WaterFlow 流式引擎构建了完整的工具调用循环:
用户输入
→ 写入 agent_memory 会话状态
→ 模型生成(generate)
└─ 判断结果是否携带工具调用(isToolCall)
├─ 是:聚合所有 toolCalls → handleTool
│ ├─ 将模型消息追加到 agent_memory
│ ├─ 调用 doToolCall 执行工具(DefaultAgent 中即 toolExecuteService.execute)
│ ├─ 将 ToolMessage 结果回填到 agent_memory
│ └─ 回到 CHECK_POINT 节点,再次触发模型生成
└─ 否:直接输出最终回答
这段循环对应 AbstractAgent.java 中的 buildFlow():.conditions().matchTo(ChatMessage::isToolCall, ...) 是分支判断,reduce 聚合多轮工具调用,.id("call tool") 执行工具后通过 .to(CHECK_POINT) 回环,形成“生成→调用→回填→再生成”的循环,直到模型给出不含工具调用的最终回答。
DefaultAgent.doToolCall 的具体实现是:将模型给出的每个 ToolCall 的 name 与 arguments 交给 toolExecuteService.execute(namespace, name, arguments),把返回文本包装成 ToolMessage 后回填给模型。整个过程对使用者完全透明,你只需声明工具并组装流程,循环调度由 Agent 自动完成。
Spring Boot 集成方式
如果项目基于 Spring Boot 运行,FEL 提供了对应的集成示例 examples/fel-spring-example/06-agent。其控制器 AgentExampleController.java 与 FIT 版本几乎一致,差异仅在 Web 层注解(@RestController、@Value 来自 org.springframework.beans.factory.annotation),Agent 的构建、工具绑定与对话流程完全复用 FEL 的同一套 API。这意味着你可以把本文的 Agent 代码平滑迁移到 Spring Boot 工程中。
常见问题与排查要点
- 工具没有被模型识别:确认
tool-maven-plugin已配置且build-toolgoal 已执行,检查编译产物中是否生成了tools.json;确认fel-tool-discoverer、fel-tool-factory-repository、fel-tool-repository-simple依赖完整,插件启动时工具才能被扫描注册。 - 模型报“工具不存在”:确认
DefaultAgent的 namespace 与@ToolMethod(namespace = ...)一致,且toolRepository.listTool(namespace)能查到工具(可通过查看工具仓库的listTool返回核对)。 - 返回内容与工具结果不符:
ChatOption.stream(false)表示非流式返回,便于一次拿到完整结果;若开启流式,需自行处理工具调用中间态。同时注意@ToolMethod.description与@Property.description越准确,模型选择正确工具的成功率越高。 - 多智能体互通:由于工具仓库与工具执行服务都是
@Genericable标注的 FIT 服务,多个 Agent(甚至跨进程部署)可以共享同一套工具注册与执行能力,这是 FEL 多智能体协作的基础设施保障。
延伸阅读
- 智能体快速入门指南全文:docs/framework/fel/java/quick-start-guide/06. 智能体.md
- 完整可运行示例:examples/fel-example/06-agent
- 工具调用与工具定义规范:被注解函数签名规范.md(FIT 侧通用约定,Java 侧语义一致)
- 模型接入与对话流程:01. 模型.md、01. AI 流程.md
- 工具服务源码:tool-service、tool-discoverer、tool-maven-plugin