🎯 今日核心问题
- 不用 LangChain4j,用 JDK 自带的 HttpClient + Jackson,最少需要多少行才能跑通一个 Agent?
- 手写的版本里,哪些部分是"框架帮我做过的事"?把它们列出来,你才真正懂框架。
- 为什么说这个 30 行的版本比框架更适合用来 debug?
📖 精读提纲
【一】30 行到底能省掉什么(又能保留什么)
Agent 的必需组件只有四个:消息列表、一次 HTTP 请求、一个工具映射表、一个带上限的 for 循环。OpenAI 兼容协议的 /v1/chat/completions 返回里,choices[0].message.tool_calls 就是模型的行动指令,finish_reason=tool_calls 告诉你该执行了。你不需要 SDK,不需要注解,不需要自动装配。
框架真正替你做的三件事:消息类型系统(把 JSON 反序列化成 UserMessage/AiMessage/ToolExecutionResultMessage)、工具注册与反射调用(从 @Tool 注解生成 JSON Schema 并做参数绑定)、会话与记忆(ChatMemory + 各种淘汰策略)。这三样在今天的手写版里分别对应:List<Map<String,Object>>、Map<String, Function<String,String>>、ConcurrentHashMap。如此而已。
【二】消息的三种骨架结构
手写版本里没有强类型,全靠 Map 拼。三条消息的形态必须刻在脑子里:
user:{"role":"user","content":"杭州今天要带伞吗"}。
assistant(带工具调用):{"role":"assistant","content":null,"tool_calls":[{"id":"call_abc","type":"function","function":{"name":"queryWeather","arguments":"{\"city\":\"杭州\"}"}}]}——注意 arguments 是字符串不是对象,这是高频坑。
tool:{"role":"tool","tool_call_id":"call_abc","content":"{\"weather\":\"小雨\"}"}——tool_call_id 必须和上面那个 id 严格对应,否则模型无法把结果和调用配对。
发回模型时,assistant 那条消息要原样回填(包括 tool_calls 数组),不能只回 content。很多人的 Agent 报 400,就是回填时把 tool_calls 字段丢了,导致 tool 消息找不到主人。另外 type 字段必须是 "function",部分厂商服务端会严格校验它;id 由模型生成,长度和格式各厂商不同,不要自己按正则解析里面的数字含义,只当作不透明字符串使用。
还有一处容易踩的坑:tools 参数里的工具定义,和消息链里的 tool_calls 是两回事。前者是你告诉模型"你有哪些能力可用"(每次请求都要带),后者是模型回答"我这轮要用哪个"。很多人以为注册过一次就够了,第二轮请求忘了带 tools,模型就再也调不出工具了——表现为第一轮正常、第二轮突然开始胡说。
【三】实战应用:Spring Boot 场景——用 HttpClient 直连,绕过所有封装
在一个 Spring Boot 3.x 项目里,用 java.net.http.HttpClient(JDK 11+ 自带,零依赖)+ Jackson ObjectMapper 就够了。把 baseUrl、apiKey、model 放 application.yml 用 @Value 注入,请求体用 Map.of(...) 组装后 writeValueAsString。
工具注册用 Map<String, Function<JsonNode, String>>:key 是工具名,value 接收已解析的参数节点、返回字符串。这样参数解析和业务逻辑解耦,加工具只是往 Map 里 put 一项。这 30 行代码建议单独放在 agent-mini 模块里,不要混进业务包,它会成为你后面所有对比实验的基线。
关于工具 schema,手写版最容易偷懒只写 name。正确的最小定义是三件套:name(动词+名词,如 queryWeather)、description(一句话说清"什么时候该用它",不是"它是干什么的")、parameters(JSON Schema,含 type/properties/required)。模型选错工具,八成是 description 写得像功能说明书而不是决策依据。比如写"查询指定城市当天天气"不够,写成"用户询问某地今天/当前天气、是否需要带伞或穿衣时使用"才让模型知道何时该调。
【四】常见误区
- ❌ 把
arguments直接当对象传。它是 JSON 字符串,需要二次readTree。少了这一步,get("city")永远 NPE。 - ❌ 忘了在 tools 定义里写
parametersschema。只给 name 和 description,模型经常编参数名。required数组要写全。 - ❌ 每轮新建 HttpClient。它是线程安全且应该复用的,做成
@Bean单例,配置连接池和 30s 超时。 - ❌ 以为手写版不能上生产。很多团队核心链路就是手写的 200 行,比框架好排查。关键是加日志、加超时、加步数上限。
💻 代码示例
// AgentMini.java —— 30 行核心逻辑,零框架依赖(JDK HttpClient + Jackson)
@Configuration
public class AgentMini {
private final HttpClient http = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10)).build();
private final ObjectMapper om = new ObjectMapper();
private final Map<String, Function<JsonNode, String>> tools = new LinkedHashMap<>();
@Value("${llm.base-url}") private String baseUrl;
@Value("${llm.api-key}") private String apiKey;
@Value("${llm.model}") private String model;
public void register(String name, Function<JsonNode, String> fn) { tools.put(name, fn); }
public String run(List<Map<String, Object>> msgs) throws Exception {
for (int i = 0; i < 6; i++) { // ① 上限 6 轮
Map<String, Object> body = Map.of(
"model", model, "messages", msgs, "tools", toolSchemas(), "temperature", 0);
HttpRequest req = HttpRequest.newBuilder(URI.create(baseUrl + "/chat/completions"))
.header("Authorization", "Bearer " + apiKey)
.header("Content-Type", "application/json")
.timeout(Duration.ofSeconds(60))
.POST(HttpRequest.BodyPublishers.ofString(om.writeValueAsString(body))).build();
JsonNode msg = om.readTree(http.send(req, HttpResponse.BodyHandlers.ofString())
.body()).path("choices").path(0).path("message"); // ② 取 assistant 消息
msgs.add(om.convertValue(msg, Map.class)); // ③ 原样回填(含 tool_calls)
JsonNode calls = msg.path("tool_calls");
if (calls.isEmpty()) return msg.path("content").asText(); // ④ 无调用 = 收工
for (JsonNode c : calls) { // ⑤ 执行 + 回灌
JsonNode args = om.readTree(c.path("function").path("arguments").asText());
String out;
try { out = tools.get(c.path("function").path("name").asText()).apply(args); }
catch (Exception e) { out = "{\"error\":\"" + e.getMessage() + "\"}"; }
msgs.add(Map.of("role", "tool", "tool_call_id", c.path("id").asText(), "content", out));
}
}
return "达到最大步数";
}
private List<Map<String, Object>> toolSchemas() { /* name/description/parameters 三件套 */ }
}
// 用法:注入后在 @PostConstruct 里注册工具
agentMini.register("queryWeather", args ->
"{\"city\":\"" + args.path("city").asText() + "\",\"weather\":\"小雨\",\"temp\":18}");
String answer = agentMini.run(new ArrayList<>(List.of(
Map.of("role", "user", "content", "杭州今天要带伞吗"))));
✏️ 今日动手
- 新建
agent-mini模块(或包),把上面的AgentMini敲进去,不要复制粘贴——手敲一遍才知道哪一行在干什么。 application.yml里配llm.base-url(DeepSeek / 通义 / 任意 OpenAI 兼容端点)、llm.api-key、llm.model,用环境变量占位,别把 key 提交进 git。- 写一个
@SpringBootTest,注册一个假queryWeather,断言run()的返回里包含"伞"字,并打印msgs.size()。跑通后把它 push 到你的agent-lab仓库。 - 对比实验:把
msgs.add(om.convertValue(msg, Map.class))这一行注释掉,再跑一次,看报什么错(预期 400:tool 消息找不到对应 tool_calls)。亲眼看一次这个错误,以后线上再遇到能秒认。
交付物:一个 30 行能跑的最小 Agent + 一份 NOTES.md,记录"框架替你做了哪三件事"。
🔖 明日预告
今天全程用 Map 拼消息,能跑但很脆——字段名拼错、role 写错都只在运行时报错。明天把消息协议彻底讲清楚:system/user/assistant/tool 四种角色的语义边界,为什么 tool 消息必须带 id,以及怎么用 record + sealed interface 在 Java 里做类型安全的建模。