400 行 Java 代码手搓 AI Agent,ReAct 循环 + Tool Call,我跑起来了
大家好,我是二哥呀。
Opus 5.5 发布后测试了几天,发现太强大了,加上GPT-6 Astra 也很牛逼,于是打算升级和重构一下PaiCLI的代码和教程。
这半年,我每天都在终端里和 Claude Code 打交道。于是我就用 Java 手搓了高仿 Claude Code 的命令行 Agent,名字就叫 PaiCLI。

这篇是 PaiCLI 系列的第 1 期。我们按 PaiCLI 现在的源码,把这个循环从头到尾拆开,看模型怎么知道有哪些工具,调用请求怎么从流式响应里拼出来,工具结果怎么安全地交回模型,第一批工具为什么这样设计,循环又在什么时候停下。
01、一次任务里模型被调用了几次
先看一个具体的任务。在 PaiCLI 里输入“把 Hello.java 里的 Hello World 改成 Hello PaiCLI”。

模型只做一件事,看完当前的对话,决定是调用工具还是直接回答。把这件事一遍遍重复下去的,是 Agent 的主循环。
这种推理和行动交替进行的模式叫 ReAct(Reasoning + Acting),每次行动的结果,又成为下一次推理的输入。

PaiCLI 的主循环长这样,为了让大家看清骨架,我省掉了日志、状态栏和异常处理。
// src/main/java/com/paicli/agent/Agent.java,runInternal 节选
while (true) {
if (CancellationContext.isCancelled()) {
return "⏹️ 已取消当前任务。";
}
injectPendingLspDiagnostics(); // 上一步改过代码,先把语法诊断补进对话
maybeCompactHistory(); // 对话太长,先压缩再请求
AgentBudget.ExitReason exitReason = budget.check();
if (exitReason != AgentBudget.ExitReason.WITHIN_BUDGET) {
return finalizePartialResult(exitReason, budget, startNanos, reasoningTranscript, streamRenderer);
}
int iteration = budget.beginIteration();
LlmClient.ChatResponse response = llmClient.chat(
conversationHistory, toolExposure.definitions(), streamRenderer);
if (response.hasToolCalls()) {
// 记下调用请求 → 执行工具 → 把结果追加进对话,第 04 节展开
continue;
}
conversationHistory.add(LlmClient.Message.assistant(response.content()));
return /* 最终回答 */;
}
while (true) 没有写轮数上限。正常的出口只有一个,就是模型这一次没有调用任何工具,程序把它的回复当成最终回答。
其余几个出口都属于意外情况。用户按了 ESC 取消,调用模型失败,或者预算和重复检测触发了收尾。

每轮调用模型之前,PaiCLI 还会补语法诊断、压缩对话历史。
02、模型怎么知道有哪些工具
循环能跑起来,前提是模型知道自己手上有哪些工具。
模型看不到 Java 代码,它能看到的只有请求体里的一份工具清单。PaiCLI 里每个工具由四样东西组成,名字、描述、参数定义和执行逻辑,前三样发给模型,执行逻辑留在本地。
以 read_file 为例。
// src/main/java/com/paicli/tool/ToolRegistry.java(节选)
tools.put("read_file", new Tool(
"read_file",
"读取文件内容(仅限项目根目录之内);可用 offset/limit 按行读取,避免把大文件整段塞进上下文",
createParameters(
new Param("path", "string", "文件路径", true),
new Param("offset", "integer", "起始行号,1 表示第一行;省略时读取全文", false),
new Param("limit", "integer", "最多读取多少行;省略时读取全文,最大 2000 行", false)
),
args -> {
Path safe = pathGuard.resolveSafe(args.get("path"));
// ……读文件,返回文本
}
));
createParameters 把这几个参数转成 JSON Schema(一种描述 JSON 结构的规范),最后和名字、描述一起放进请求体的 tools 字段。
{
"type": "function",
"function": {
"name": "read_file",
"description": "读取文件内容(仅限项目根目录之内);可用 offset/limit 按行读取,避免把大文件整段塞进上下文",
"parameters": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "文件路径" },
"offset": { "type": "integer", "descript...未能定位到原文的划线
企业级Agent工作流编排项目PaiFlow
Vibe Coding版本的PaiAgent
派聪明RAG AI知识库Java版本+Go版本
微服务 PmHub、技术派、MYDB
求职派JobClaw(OpenClaw/Hermes架构
PaiCLI(类似Claude Code的Agent
派简历(代码已完成)
等实战项目。
1. 微信扫右侧的优惠券加入知识星球
2. 解锁星球的实战项目教程和源码: 项目源码+教程获取
热门评论
回复