Agent

关于 Agent

让我们一起来探索 Feat AI 框架中强大的 Agent 组件！Agent 是 Feat AI 的核心功能之一，它基于 ReAct（Reasoning + Acting）范式，能够像人一样思考和行动，通过推理和执行操作来解决复杂任务。

想象一下，如果你有一个智能助手，不仅能理解你的需求，还能主动采取行动去完成任务，比如搜索信息、操作文件、管理待办事项等等，这就是 Agent 的魅力所在！

注意

在开始使用 Agent 之前，请确保已正确配置 Feat AI 模块并添加了相应的依赖。

1. 快速上手

1.1 创建你的第一个 Agent

我们从一个简单的例子开始，创建一个基本的 ReActAgent 实例并执行任务：

import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.FeatAgent;

// 创建一个 ReActAgent 实例
FeatAgent agent = new ReActAgent();

// 执行任务
String result = agent.execute("帮我搜索一下最新的 AI 技术发展趋势");
System.out.println(result);

这个简单的例子展示了 Agent 的强大能力。只需几行代码，你就拥有了一个可以理解自然语言并执行复杂任务的智能助手！

有关完整示例，请参见 ReActAgentTest.java

1.2 配置 Agent 选项

在实际应用中，你可能需要根据具体需求对 Agent 进行配置。下面是如何自定义 Agent 选项：

import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.AgentOptions;
import tech.smartboot.feat.ai.chat.ChatModelVendor;

// 创建 Agent 配置
AgentOptions options = AgentOptions.create()
    .maxIterations(15)                         // 设置最大推理迭代次数
    .chatOptions()
    .model(ChatModelVendor.GiteeAI.DeepSeek_V32_EXP); // 设置使用的模型

// 创建 Agent 实例
ReActAgent agent = new ReActAgent();
agent.options.maxIterations(15)
    .chatOptions()
    .model(ChatModelVendor.GiteeAI.DeepSeek_V32_EXP);

通过这些配置，你可以控制 Agent 的行为，比如设置最大迭代次数防止无限循环，或者选择更适合任务的 AI 模型。

2. 核心概念解析

2.1 ReAct 范式详解

ReAct（Reasoning + Acting）是 Agent 的核心工作原理。这个范式让 Agent 能够像人一样通过思考和行动来解决问题：

1. 思考（Thought） - 分析当前情况和目标
2. 行动（Action） - 执行具体的操作
3. 观察（Observation） - 获取行动结果并据此继续推理

这个循环过程让 Agent 能够解决复杂的多步骤任务。

graph TD A[开始] --> B[思考] B --> C[执行动作] C --> D[观察结果] D --> E{是否完成?} E -->|否| B E -->|是| F[返回最终答案]

2.2 Agent 状态管理

Agent 在执行过程中会经历不同的状态，了解这些状态有助于你更好地监控和调试：

• IDLE - 空闲状态，表示 Agent 当前没有任务正在执行，可以接受新的任务
• RUNNING - 运行状态，表示 Agent 正在处理任务的主逻辑阶段
• TOOL_EXECUTION - 工具执行状态，表示 Agent 正在调用外部工具或执行特定的功能模块
• FINISHED - 完成状态，表示 Agent 已经成功完成了当前的任务
• ERROR - 错误状态，表示 Agent 在执行过程中遇到了异常或错误

你可以通过以下方式获取 Agent 的当前状态：

AgentState state = agent.getState();
System.out.println("当前状态: " + state);

3. Agent 架构设计

Feat AI Agent 采用了模块化设计，主要包括以下几个核心组件：

graph TB A[Agent接口] --> B[FeatAgent抽象类] B --> C[ReActAgent实现类] C --> D[AgentOptions配置] C --> E[AgentState状态管理] C --> F[AgentTool工具接口] F --> G[TodoListTool] F --> H[FileOperationTool] F --> I[SearchTool] F --> J[WebPageReaderTool] F --> K[SubAgentTool] D --> L[PromptTemplate提示模板] D --> M[ChatOptions聊天选项] C --> N[Memory记忆管理] style C fill:#FFE4B5,stroke:#333 style D fill:#E6E6FA,stroke:#333 style F fill:#E6E6FA,stroke:#333

3.1 核心组件说明

1. Agent接口 - 定义了Agent的基本行为，主要是execute方法
2. FeatAgent抽象类 - 提供了Agent的基础实现，包括状态管理和配置选项
3. ReActAgent实现类 - 基于ReAct范式的具体实现，是用户直接使用的类
4. AgentOptions配置 - 管理Agent的各种配置选项，包括工具、提示模板、聊天选项等
5. AgentState状态管理 - 管理Agent的运行状态
6. AgentTool工具接口 - 定义了工具的基本规范，所有工具都需要实现此接口
7. 内置工具实现 - 提供了常用的工具实现，如文件操作、搜索等
8. PromptTemplate提示模板 - 管理Agent的行为提示模板
9. Memory记忆管理 - 管理Agent的记忆信息

3.2 工作流程

Agent 的工作流程如下图所示：

sequenceDiagram participant U as 用户 participant R as ReActAgent participant T as 工具 participant M as 模型 U->>R: execute(任务) loop ReAct循环 R->>M: 发送提示和任务 M->>R: 返回思考和行动 R->>T: 执行工具 T->>R: 返回结果 end R->>U: 返回最终结果

4. 内置工具详解

Feat AI Agent 内置了多种常用工具，在 ReActAgent 构造函数中默认注册。这些工具可以让 Agent 执行各种实际操作来完成复杂任务。

4.1 待办事项工具 (TodoListTool)

管理待办事项列表，可用于任务分解和进度跟踪：

// 创建待办事项列表
Action: todo_list
Action Input: {
  "action": "create"
}

// 添加待办事项
Action: todo_list
Action Input: {
  "action": "add",
  "list_id": "todo_list_1234567890",
  "title": "完成项目文档",
  "description": "编写 Feat AI 的使用文档"
}

// 列出所有待办事项
Action: todo_list
Action Input: {
  "action": "list",
  "list_id": "todo_list_1234567890"
}

// 完成待办事项
Action: todo_list
Action Input: {
  "action": "complete",
  "list_id": "todo_list_1234567890",
  "item_id": 1
}

// 移除待办事项
Action: todo_list
Action Input: {
  "action": "remove",
  "list_id": "todo_list_1234567890",
  "item_id": 1
}

4.2 文件操作工具 (FileOperationTool)

执行文件系统操作，包括读写文件、创建目录等：

// 列出目录内容
Action: file_operation
Action Input: {
  "action": "list_directory",
  "path": "./",
  "recursive": false
}

// 读取文件
Action: file_operation
Action Input: {
  "action": "read_file",
  "path": "./README.md"
}

// 写入文件
Action: file_operation
Action Input: {
  "action": "write_file",
  "path": "./output.txt",
  "content": "这是写入的内容"
}

// 创建目录
Action: file_operation
Action Input: {
  "action": "create_directory",
  "path": "./new_directory"
}

// 删除文件
Action: file_operation
Action Input: {
  "action": "delete_file",
  "path": "./unwanted.txt"
}

// 检查文件是否存在
Action: file_operation
Action Input: {
  "action": "file_exists",
  "path": "./important.txt"
}

4.3 搜索工具 (SearchTool)

执行网络搜索，获取实时信息：

// 使用百度搜索
Action: search
Action Input: {
  "query": "最新的 AI 技术发展趋势",
  "engine": "baidu",
  "max_results": 5
}

// 使用必应搜索
Action: search
Action Input: {
  "query": "最新的 AI 技术发展趋势",
  "engine": "bing",
  "max_results": 5
}

4.4 网页阅读工具 (WebPageReaderTool)

读取网页内容，提取文本信息：

// 读取网页
Action: web_page_reader
Action Input: {
  "url": "https://example.com/article"
}

4.5 子 Agent 工具 (SubAgentTool)

创建子 Agent 来处理特定任务，实现任务委派：

// 创建子 Agent
Action: sub_agent
Action Input: {
  "agent_name": "analysis_agent",
  "task": "分析这份报告的主要观点"
}

5. 扩展功能：自定义工具

除了内置工具外，你还可以创建自定义工具来扩展 Agent 的功能。自定义工具需要实现 AgentTool 接口：

import tech.smartboot.feat.ai.agent.AgentTool;
import com.alibaba.fastjson2.JSONObject;

public class CustomTool implements AgentTool {

    @Override
    public String execute(JSONObject parameters) {
        // 实现工具的具体逻辑
        return "工具执行结果";
    }

    @Override
    public String getName() {
        return "custom_tool";
    }

    @Override
    public String getDescription() {
        return "这是一个自定义工具";
    }

    @Override
    public String getParametersSchema() {
        // 返回参数定义的 JSON Schema
        return "{\n" +
               "  \"type\": \"object\",\n" +
               "  \"properties\": {\n" +
               "    \"param1\": {\"type\": \"string\"}\n" +
               "  }\n" +
               "}";
    }
}

// 注册自定义工具
AgentOptions options = AgentOptions.create();
options.addTool(new CustomTool());

通过自定义工具，你可以让 Agent 具备特定领域的专业能力，比如数据库操作、API 调用等。

6. 高级功能

6.1 内存管理

Agent 具有内存管理功能，可以存储和检索相关信息：

import tech.smartboot.feat.ai.agent.memory.AgentMemory;
import tech.smartboot.feat.ai.agent.memory.DefaultAgentMemory;

// 创建自定义内存管理器
AgentMemory memory = new DefaultAgentMemory();
AgentOptions options = AgentOptions.create()
    .memory(memory);

// 或者在创建 Agent 时配置
ReActAgent agent = new ReActAgent();

内存管理配置选项：

选项	描述	默认值
memory	Agent 记忆实例	DefaultAgentMemory
enableSmartMemory	是否启用智能记忆检索	true
memoryRetrievalThreshold	记忆检索阈值	0.5
maxMemoryRetrievalCount	最大记忆检索数量	5
maxIterations	最大推理迭代次数	20

6.2 提示模板

Agent 使用提示模板来引导 AI 模型的行为。默认使用 feat_react_agent.tpl 模板，其中包含了以下变量：

• {{tool_descriptions}} - 所有工具的描述信息
• {{tool_names}} - 所有工具名称列表
• {{date}} - 当前日期时间
• {{history}} - 历史对话记录
• {{input}} - 用户输入的任务
• {{agent_scratchpad}} - Agent 的推理过程记录

提示模板内容如下：

你是基于ReAct范式的AI智能体，能够通过推理(Thought)和行动(Action)来解决问题。

## 角色与目标
作为AI智能体，你的目标是准确理解用户的需求，并通过合理的推理和必要的工具调用来提供最佳解决方案。

## 可用工具
你可以使用的工具如下：

{{tool_descriptions}}

## 行动准则
1. 分析用户请求，判断是否需要使用工具
2. 如需使用工具，必须严格按照以下格式输出：
   Thought: 分析为什么需要这个工具
   Action: 从[{{tool_names}}]中选择合适的工具
   Action Input: 工具参数
3. 等待观察工具执行结果(Observation)
4. 根据观察结果继续推理或给出最终答案

## 输出格式
当你需要使用工具时，请严格按以下格式输出：

Thought: 详细说明为什么要使用该工具 Action: 工具名称 Action Input: 工具参数 Observation: 工具执行结果

当你已经获得足够信息可以回答用户时，请按以下格式输出：

Thought: 总结推理过程并解释答案 AI: 最终答案

## 上下文信息
当前日期时间: {{date}}

## 相关历史记忆
以下是与当前任务相关的记忆信息：
{{relevant_memories}}

## 当前任务
{{input}}

## 推理过程
{{agent_scratchpad}}

请严格按照上述格式进行思考和输出，每一步只能输出一个Thought和一个Action或AI回答。

7. 实战案例与最佳实践

7.1 完整使用示例

让我们通过一个完整的示例来展示 Agent 的强大功能：

import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.FeatAgent;

public class AgentDemo {
    public static void main(String[] args) {
        // 创建 Agent 实例
        FeatAgent agent = new ReActAgent();

        // 执行任务
        String result = agent.execute("阅读spring官方文档，对比下spring4和3的差别，生成一份详细的分析报告");
        System.out.println("任务结果:");
        System.out.println(result);
    }
}

有关完整示例，请参见 ReActAgentTest.java

7.2 最佳实践建议

在使用 Agent 时，遵循以下最佳实践可以让你获得更好的效果：

1. 合理设置迭代次数 - 根据任务复杂度设置合适的最大迭代次数，避免无限循环
2. 选择合适模型 - 根据任务需求选择具有相应能力的模型
3. 工具组合使用 - 合理组合不同工具以完成复杂任务
4. 监控 Agent 状态 - 通过状态监控了解 Agent 的执行过程
5. 错误处理 - 妥善处理执行过程中可能出现的异常情况

提示

小贴士：在实际应用中，建议为复杂的任务提供更详细的指导，帮助 Agent 更好地理解你的需求。

通过本教程，你已经掌握了 Feat AI Agent 的核心功能和使用方法。现在你可以开始构建自己的智能应用了！