FEL 智能体(Agent)开发指南:基于 FIT 函数构建工具调用型 AI 助手

原创2026-10-14 23:01:531,857 阅读
文章标签:后端人工智能AI 应用Agent 框架RAGMCP 服务MCP Clients微服务插件系统流程编排依赖注入

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 设计模式:

  1. Reflection:让 Agent 审视和修正自己生成的输出;
  2. Tool Use:LLM 生成代码、调用 API 等进行实际操作;
  3. Planning:让 Agent 分解复杂任务并按计划执行;
  4. 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 的工具体系由三层服务协作完成:

  1. 发现层:fel-tool-discoverer 中的 DefaultToolDiscoverer.java 实现了 FIT 的 PluginStartedObserver / PluginStoppingObserver。当插件启动时,它会扫描插件资源中的 tools.json 清单(该清单正是 tool-maven-plugin 在编译期生成的),反序列化出 ToolGroupEntity → ToolEntity,并逐个注册进 ToolRepository;插件停止时则批量删除对应工具。
  2. 存储层:ToolRepository 接口(ToolRepository.java)提供 addTool、deleteTool、getTool、listTool(namespace) 四个能力,接口方法均标注了 @Genericable(id = "modelengine.fel.tool.*"),意味着工具仓库本身也是一个可远程调用的 FIT 服务——这是多智能体、多进程共享工具注册中心的基础。
  3. 执行层: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-tool goal 已执行,检查编译产物中是否生成了 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 多智能体协作的基础设施保障。

延伸阅读

登录后查看全文
fit-framework