核心概念详解：理解 Agent、Session、Model、Tool、Skill

前言

在上一篇文章中，我们用几行代码创建了第一个 Agent。但如果你想真正掌握 Agent4J，就需要理解它的核心概念。

就像学开车，你不需要知道发动机是怎么工作的，但你需要知道方向盘、油门、刹车是干什么的。

Agent4J 有五个核心概念：

Agent：智能体本身
Session：会话管理
Model：LLM 模型
Tool：工具
Skill：技能组

让我一个一个解释。

1. Agent（智能体）

AgentClient 是 Agent4J 的核心类。它代表一个智能体，就像一个员工，你需要告诉它：

名字：它叫什么
描述：它是什么角色，擅长做什么
模型：它用哪个 LLM 来思考
工具：它有哪些能力

AgentClient agent = new AgentClient();
agent.setName("CodeAssistant");
agent.setDescription("一个资深的 Java 开发工程师，擅长代码审查和重构");
agent.setModel(llm);
agent.getTools().add(new MyCustomTool());
agent.getSkills().addAll(BuiltInSkills.all());

描述的重要性

你可能觉得 setDescription 只是一个装饰，但其实它很重要。

LLM 会根据这个描述来理解自己的角色。如果你说它是一个"资深的 Java 开发工程师"，它就会用更专业的视角来回答问题；如果你说它是一个"耐心的教学助手"，它就会用更通俗易懂的方式来解释概念。

这就像你给员工分配岗位一样，描述越清晰，员工越知道该怎么做事。

2. Session（会话）

AgentClientSession 代表一次会话。每个会话都有独立的对话历史，就像你和某个人的一次聊天记录。

AgentClientSession session = agent.createSession();

// 发送消息
session.command("你好")
    .then(handler)
    .error(errorHandler);

// 继续对话
session.command("刚才你说的什么意思？")
    .then(handler)
    .error(errorHandler);

会话的生命周期

一个会话可以包含多轮对话。Agent4J 会自动维护对话历史，这样 LLM 就能理解上下文。

但要注意，对话历史越长，消耗的 Token 就越多。所以：

对于简单的问答，每次创建新会话
对于需要上下文的任务，使用同一个会话
对于长时间运行的任务，考虑使用会话序列化

会话序列化

你可以把会话保存下来，以后恢复：

// 保存会话
String json = session.serialization();

// 恢复会话
AgentClientSession restored = agent.getSessionFromSerialization(json);

这对于需要长时间运行的任务很有用。你可以把会话保存到数据库，下次再继续。

3. Model（模型）

LLMModel 是 Agent4J 对 LLM 的抽象。它隐藏了不同 LLM 提供商的差异，让你用统一的接口调用不同的模型。

// 小米 MiMo（推荐）
LLMModel mimo = LLMModel.create(
    ModelType.OpenAI, 
    "https://token-plan-cn.xiaomimimo.com", 
    "mimo-v-2.5-pro", 
    "your-api-key"
);

// Anthropic Claude
LLMModel claude = LLMModel.create(
    ModelType.Anthropic, 
    "https://api.anthropic.com", 
    "claude-sonnet-4", 
    "sk-..."
);

// OpenAI
LLMModel deepseek = LLMModel.create(
    ModelType.Response, 
    "https://api.openai.com", 
    "gpt-5.5", 
    "sk-..."
);

为什么不直接用 HTTP 调用？

你可能会想：我自己用 OkHttp 调用 API 不就行了？为什么要用 LLMModel？

因为：

统一接口：不同提供商的 API 格式不同，LLMModel 帮你处理了这些差异
流式响应：SSE 流式解析很麻烦，LLMModel 帮你处理了
工具调用：不同提供商的工具调用格式不同，LLMModel 帮你统一了
错误处理：网络错误、API 限流、Token 超限……LLMModel 帮你处理了

你只需要关注业务逻辑，不用操心底层细节。

4. Tool（工具）

Tool 是 Agent 的能力。没有工具的 Agent 只能聊天，有了工具的 Agent 能做事情。

Agent4J 的工具系统设计得非常简单：

// 定义参数
public class SearchParam extends ToolParam {
    @Param(description = "搜索关键词")
    private String query;
    
    @Param(required = false, description = "最大结果数")
    private String limit;
    
    // getter 和 setter
}

// 实现工具
@ToolInfo(name = "web_search", description = "搜索网页")
public class WebSearchTool implements Tool<SearchParam> {
    @Override
    public String execute(SearchParam param) {
        // 实现搜索逻辑
        return searchWeb(param.getQuery(), param.getLimit());
    }
}

// 注册工具
agent.getTools().add(new WebSearchTool());

工具的工作流程

LLM 决定调用工具：根据用户的问题和工具的描述，LLM 决定需要调用哪个工具
框架解析参数：Agent4J 自动把 LLM 返回的 JSON 参数解析成 ToolParam 对象
执行工具：调用 Tool.execute() 方法
返回结果：把工具的返回值反馈给 LLM
LLM 继续思考：LLM 根据工具的结果继续回答问题

这个过程会自动循环，直到 LLM 认为不需要再调用工具为止。

工具描述的重要性

LLM 是根据工具的描述来决定是否调用它的。所以：

工具名要清晰明了
描述要准确说明工具能做什么
参数描述要详细说明每个参数的含义和格式

这就像你给员工一份工作说明书，写得越清楚，员工越知道该怎么用这些工具。

5. Skill（技能组）

Skill 是一组相关工具的集合，加上一份使用指南。

Skill webSkill = new Skill(
    "Web Research",                                    // 技能名称
    "从网页上搜索和获取信息",                             // 技能描述
    List.of(new WebSearchTool(), new WebFetchTool()),  // 工具列表
    """
    ## 网页搜索指南
    - 使用 `web_search` 搜索相关网页
    - 使用 `web_fetch` 获取网页完整内容
    - 回答时要注明来源
    """);                                              // 使用指南

为什么要用 Skill？

组织工具：把相关的工具分组，便于管理
提供指南：告诉 LLM 如何使用这些工具
按需加载：你可以只给 Agent 添加需要的技能，而不是所有工具

内置技能

Agent4J 提供了三个内置技能：

FileSystem（文件系统）

list_directory_tree：浏览目录结构
view_file：读取文件内容
create_file：创建文件
edit_file：编辑文件
delete_file：删除文件
move_file：移动或重命名文件
search_in_file：在文件中搜索
search_in_directory：在目录中搜索
search_files：按文件名搜索

CommandExecution（命令执行）

execute_command：执行 Shell 命令

Orchestration（编排）

create_plan：创建执行计划
create_sub_agent：生成子 Agent

// 添加所有内置技能
agent.getSkills().addAll(BuiltInSkills.all());

// 或者只添加需要的技能
agent.getSkills().add(BuiltInSkills.fileSystem());
agent.getSkills().add(BuiltInSkills.commandExecution());

核心概念之间的关系

让我用一个比喻来解释这些概念的关系：

Agent 就像一个员工
Model 就像员工的大脑
Tool 就像员工的工具箱
Skill 就像员工的技能证书
Session 就像你和员工的一次对话

你（用户）通过 Session 和 Agent 对话，Agent 用 Model 思考，用 Tool 做事，用 Skill 指导如何使用工具。

用户 → Session → Agent → Model（思考）
                    ↓
                  Tool（执行）
                    ↓
                  Skill（指导）
                    ↓
                  返回结果给用户

实际例子

让我用一个实际的例子来说明这些概念是如何协同工作的：

让我用一个实际的例子来说明这些概念是如何协同工作的：

```java
// 创建模型
LLMModel llm = LLMModel.create(ModelType.OpenAI, "https://token-plan-cn.xiaomimimo.com", "mimo-v-2.5-pro", "your-api-key");

// 创建 Agent
AgentClient agent = new AgentClient();
agent.setName("FileOrganizer");
agent.setDescription("一个文件整理助手，擅长整理杂乱的文件");
agent.setModel(llm);
agent.getSkills().addAll(BuiltInSkills.all());

// 创建会话
AgentClientSession session = agent.createSession();

// 发送任务
session.command("请帮我整理当前目录下的文件，把所有 Java 文件放到 src 目录，所有配置文件放到 config 目录")
    .then(new AgentResultHandler() {
        public void onMessage(String msg) { 
            System.out.print(msg); 
        }
        
        public void onTool(ToolDescriptor tool, ToolStatus status) {
            System.out.println("[" + status + "] " + tool.getName());
        }
    })
    .error(e -> e.printStackTrace());

在这个例子中：

Agent 是 FileOrganizer，它是一个文件整理助手
Model 是 MiMo，它负责思考如何完成任务
Skill 是 BuiltInSkills.all()，它提供了文件系统和命令执行的能力
Session 是 session，它管理你和 Agent 的对话
Tool 会在需要时自动调用，比如 list_directory_tree、move_file 等

Agent4J 的五个核心概念：

Agent：智能体，定义了"谁"在做事
Session：会话，管理对话历史和上下文
Model：模型，Agent 的大脑
Tool：工具，Agent 的能力
Skill：技能组，工具的集合和使用指南

理解了这些概念，你就掌握了 Agent4J 的基础。接下来，让我们看看这些内置工具具体能做什么。

项目地址：https://github.com/onlyGuo/agent4j

上一篇：快速开始：5 分钟跑通第一个 Agent

下一篇：内置工具与技能：Agent 开箱即用的能力