Java 团队接入 AI Agent 时，真正棘手的通常不是发出一次模型请求，而是长期维护模型适配、工具调用、会话状态、提示词和知识检索。Qualia 的定位正是从这些企业项目中的重复问题出发：它不是简单复刻其他语言的 Agent 框架，而是尝试用模块化方式，把 AI 能力放进 Java 开发者熟悉的工程边界中。
Agent 落地难在模型之外
一个演示程序可能只需要拼接提示词并调用模型 API，但进入生产环境后，代码很快会出现几类分裂：
- 不同模型供应商使用不同的请求结构、鉴权方式和流式协议。
- 工具散落在业务服务里，参数校验、异常处理和权限控制缺乏统一入口。
- 多轮对话需要保存历史记录，还要处理窗口裁剪、并发更新和数据隔离。
- 提示词被硬编码在控制器或服务类中，无法复用、测试和独立迭代。
- 每个项目都重新实现文档切分、召回、上下文组装等检索流程。
这些问题不能只靠一个更长的 AgentService 解决。Qualia 所强调的模块化设计，价值在于把变化速度不同的部分拆开：模型可以替换，工具可以注册，会话状态可以迁移到持久化存储，提示词和检索逻辑也能独立演进。
用 Java 接口明确五类职责
由于摘要没有给出 Qualia 的具体包名和 API，下面不是官方用法，而是一个可以直接运行的最小示例，用来说明这类框架在 Java 项目中可以如何划分职责。
将以下内容保存为 AgentDemo.java。它只依赖 Java 17 标准库：
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AgentDemo {
record Message(String role, String content) {}
interface ChatModel {
String generate(List<Message> messages);
}
interface Tool {
String name();
String execute(String input);
}
interface SessionStore {
List<Message> load(String sessionId);
void append(String sessionId, Message message);
}
static final class InMemorySessionStore implements SessionStore {
private final Map<String, List<Message>> sessions = new HashMap<>();
public List<Message> load(String sessionId) {
return new ArrayList<>(sessions.getOrDefault(sessionId, List.of()));
}
public void append(String sessionId, Message message) {
sessions.computeIfAbsent(sessionId, ignored -> new ArrayList<>())
.add(message);
}
}
static final class Agent {
private final ChatModel model;
private final SessionStore sessions;
private final Map<String, Tool> tools;
private final String systemPrompt;
Agent(ChatModel model, SessionStore sessions, List<Tool> tools,
String systemPrompt) {
this.model = model;
this.sessions = sessions;
this.systemPrompt = systemPrompt;
this.tools = new HashMap<>();
tools.forEach(tool -> this.tools.put(tool.name(), tool));
}
String chat(String sessionId, String input) {
sessions.append(sessionId, new Message("user", input));
List<Message> context = new ArrayList<>();
context.add(new Message("system", systemPrompt));
context.addAll(sessions.load(sessionId));
String answer;
if (input.startsWith("time:")) {
Tool tool = tools.get("clock");
answer = tool == null
? "clock tool is unavailable"
: "Tool result: " + tool.execute(input.substring(5).trim());
} else {
answer = model.generate(context);
}
sessions.append(sessionId, new Message("assistant", answer));
return answer;
}
}
public static void main(String[] args) {
ChatModel fakeModel = messages ->
"Received " + messages.size() + " messages; latest input: "
+ messages.get(messages.size() - 1).content();
Tool clock = new Tool() {
public String name() {
return "clock";
}
public String execute(String zone) {
return "Requested time zone: " +
(zone.isBlank() ? "system default" : zone);
}
};
Agent agent = new Agent(
fakeModel,
new InMemorySessionStore(),
List.of(clock),
"Answer concisely and cite tool results explicitly."
);
System.out.println(agent.chat("session-42", "Explain modular agents"));
System.out.println(agent.chat("session-42", "time: Asia/Shanghai"));
}
}
编译并运行：
javac AgentDemo.java
java AgentDemo
这个示例故意使用假模型，避免把某家供应商的 API 冒充成 Qualia 的真实接口。接入实际项目时，可以把 ChatModel 替换为 Qualia 提供的模型适配模块，把 SessionStore 接到 Redis 或数据库，并通过框架的工具机制注册受控的业务能力。具体类名和配置方式应以项目当前文档及版本为准。
模块化不只是代码整洁
模型抽象解决的是供应商差异，但生产系统还需要控制替换成本。例如，从一个模型切换到另一个模型时，除了请求字段，还可能遇到工具调用格式、上下文长度、流式事件和错误码的差异。统一接口应保留供应商特有能力的扩展点，不能把所有模型强行压缩成最低共同能力。
工具系统的重点则是治理。一个“查询订单”工具不仅是 Java 方法，还应包含参数约束、调用身份、超时、审计和返回值裁剪。尤其不能让模型直接拼接 SQL、Shell 命令或内部 HTTP 地址。模型负责提出调用意图，确定性代码负责验证并执行。
会话状态也不等同于保存完整消息列表。生产环境通常要进一步考虑：
- 按租户和用户隔离会话数据。
- 设置消息数量、Token 数量或保存时间上限。
- 对敏感字段进行脱敏或加密。
- 使用乐观锁或版本号处理同一会话的并发写入。
- 区分短期对话记录与可长期召回的用户记忆。
提示词复用和知识检索同样需要版本管理。提示词变化会影响输出行为，检索参数变化会影响召回结果；两者都应该进入测试和发布流程，而不是作为不可追踪的字符串散落在代码中。
接入 Qualia 前先做一轮工程核对
Qualia 面向 Java 的价值，需要通过实际依赖关系、扩展接口和运行指标来验证。团队可以从一条低风险工作流开始，例如内部知识问答或只读数据查询，并检查以下事项：
- 当前版本支持哪些模型，以及切换模型需要修改多少业务代码。
- 工具参数是否具备结构化校验，失败是否能够重试或降级。
- 会话状态能否接入现有 Redis、数据库和数据保留策略。
- 提示词是否支持集中管理、版本追踪和自动化测试。
- 检索模块能否替换向量存储、嵌入模型和重排策略。
- 是否能够记录模型耗时、Token 消耗、工具调用与最终错误。
不要一开始就把支付、删除或审批等高风险操作交给 Agent。先使用只读工具，加入超时、调用额度、人工确认和审计日志，再逐步扩大权限。
Qualia 值得关注的地方，不是又增加了一种调用大模型的方法，而是把 Java 团队反复遇到的 AI 工程问题收拢到清晰的模块中。是否采用它，最终应由可替换性、可观测性、安全边界和团队维护成本决定，而不是由一次演示中的回答效果决定。