AI Agent 从 0 到 1：概念、执行逻辑、Java 选型与 Harness
这是一篇总览篇：目标是把 AI Agent 的全局认知一次性立起来——它是什么、怎么跑、Java 里怎么落地、以及为什么"裸调大模型"和"可靠的 Agent 产品"之间隔着一整个工程层（Harness）。文中每个话题只展开到"建立坐标系"的深度，细节拆到文档区 AI 学习地图，随学习进度逐步填充，本文是活的索引。
1. 自主性跃迁：从 Chatbot 到 Agent
理解 Agent 的第一件事不是"它能用工具"，而是控制权在谁手里：
| 形态 | 控制权 | 人类角色 | 典型例子 |
|---|---|---|---|
| Chatbot | 人类逐步指挥，模型单轮应答 | 提问者 | 问答、翻译、摘要 |
| Copilot | 模型建议，人类执行并决策 | 审批者/执行者 | 代码补全、写作助手 |
| Workflow | 代码编排流程，模型在固定节点被调用 | 流程设计者 | "先检索→再总结→再评分"的管道 |
| Agent | 模型自己决定下一步做什么、何时结束 | 目标下达者 | Coding Agent、Deep Research |
关键分界线是 Workflow vs Agent（这也是选型时最容易混淆的概念）：
Workflow：开发者用代码预先写好 LLM 的调用路径，每一步做什么、怎么跳转，都是确定的。LLM 是"被编排的节点"。
Agent：开发者只给目标和工具集，LLM 在循环中动态决定调用哪个工具、是否继续。LLM 是"编排者"。
代价结构完全不同：Workflow 可预测、好调试、成本可控；Agent 灵活但路径不确定，必须依赖工程手段兜底（这是第 5 节 Harness 存在的原因）。实践原则：能用 Workflow 解决的，不要上 Agent。
2. 分类地图：三个正交维度
业界对 Agent 的分类口径很乱，用三个维度可以拆干净：
维度一：按自主程度（横向光谱）
Workflow ──> 受限 Agent（部分环节自主）──> 完全自主 Agent（端到端目标驱动）
维度二：按架构模式（怎么组织推理）
| 模式 | 核心机制 | 适用 |
|---|---|---|
| ReAct | Reason + Act 交替：想一步、做一步、看结果再想 | 通用骨架，绝大多数 Agent 的底层 |
| Plan-and-Execute | 先生成完整计划，再逐步执行，可重规划 | 长任务、需要全局视野 |
| Reflection | 生成后自检/批评，再修订 | 对输出质量敏感的场景 |
| Router | 先分类，再分发到专门处理器 | 意图识别、多技能分流 |
| Multi-Agent | 多个角色协作（编排者-执行者、辩论、流水线） | 上下文隔离、角色专业化 |
维度三：按应用形态（做成什么产品）
- Coding Agent：Claude Code、OpenCode、Codex——在沙箱里读写代码、跑测试的反馈闭环
- Deep Research：多轮检索→综合→成文
- Computer Use / GUI Agent：操作浏览器和桌面
- 业务 Agent：客服、数据分析、运维排障，嵌入企业流程
记住这个坐标系就够了：说任何一个 Agent，先问三个问题——自主程度多高？什么架构模式？什么应用形态？
3. 执行逻辑：一个循环讲透
剥掉所有包装，Agent 的核心就是一个 LLM 循环（Agent Loop）：
┌─────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ ┌─────────┐ ┌────────────┐ │
│ │ 构造上下文 │───>│ LLM 推理 │───>│ 返回 tool │ │
│ │ (prompt + │ │ │ │ call 或文本 │ │
│ │ 历史+工具)│ └─────────┘ └─────┬──────┘ │
│ └────▲─────┘ │ │
│ │ 是 tool call │
│ │ ▼ │
│ ┌────┴──────┐ ┌──────────┐ ┌──────────┐ │
│ │ 追加观测结果 │<───│ 执行工具 │<─│ 解析参数 │ │
│ │ (observation)│ │ (sandbox)│ │ (JSON) │ │
│ └───────────┘ └──────────┘ └──────────┘ │
│ │
│ 终止条件：模型输出纯文本 / 达到迭代上限 / 人工中断 │
└─────────────────────────────────────────────────┘
逐环节的要点（每个点在文档区都有独立细化）：
- 上下文构造：system prompt（角色+规则）+ 工具定义 + 历史消息 + 规则文件（如 AGENTS.md）的注入。上下文不是越多越好——这是 context 与 memory 的核心议题。
- 推理：模型基于当前上下文输出。注意 LLM 是无状态的，"记忆"全靠每次重新喂上下文。
- Tool Calling：模型输出的不是魔法，是结构化的函数调用意图（名称+JSON 参数），由外部 runtime 校验并执行。模型只"点菜"，执行永远在引擎侧。
- Observation 回填：工具结果作为消息追加回上下文，进入下一轮。上下文窗口就是 Agent 的工作内存，长任务会撑爆，所以需要压缩/摘要/外部记忆。
- 终止条件：三个出口——模型认为完成（输出纯文本）、迭代上限熔断、人工中断。上限熔断是必需的保险丝，防止死循环烧钱。
一个反直觉的结论：Agent 没有任何单一组件是"智能"的，智能来自"循环 + 工具 + 好的上下文管理"的组合。 理解了这一点，就看懂了所有 Agent 框架——它们本质上都在做同一件事：把这个循环工程化。
4. Java 落地：框架怎么选
先说结论表，再看理由：
| 方案 | 定位 | 何时选 |
|---|---|---|
| Spring AI | Spring 官方，ChatClient 抽象 + tool calling + 各家模型适配 | 已有 Spring Boot 技术栈，要的是"AI 能力的标准化接入" |
| Spring AI Alibaba | 基于 Spring AI，加多 Agent 图编排、A2A 协议、DashScope 深度集成 | 需要多 Agent 协作/复杂流程编排，且接受阿里系模型生态 |
| LangChain4j | LangChain 设计理念在 Java 的独立实现，AiServices 声明式接口 | 想要 LangChain 生态的抽象（Memory/RAG/Tools），不绑定 Spring |
| 裸调 SDK | 直接用 OpenAI 兼容 SDK 手写 Agent Loop | 学习原理、或循环逻辑简单到不值得引框架 |
选型判断逻辑（按顺序问自己）：
- 只是给现有应用加 LLM 能力（问答/摘要/RAG 检索）？→ Spring AI，别过度设计。
- 需要 Agent 自主循环或多个 Agent 协作？→ 在 Spring AI Alibaba（Spring 系、图编排）和 LangChain4j（社区活跃、抽象丰富）之间选，前者胜在与 Spring 生态的一致性，后者胜在迭代速度。
- 想真正吃透执行逻辑？→ 裸调 SDK 手写一遍循环，再回头看框架，会看到所有框架都只是第 3 节那个循环的包装。
Python 参照系（对照看设计理念即可，不必深入）：LangChain 是"组件库"思路——链式组合各种抽象；LangGraph 把 Agent 建模为显式状态图，节点是步骤、边是跳转、状态在图里流转，用 checkpoint 支持持久化和人工介入（HITL）。Java 生态整体落后 Python 半拍，但工程化程度（类型安全、可测试性、运维成熟度）是反向优势——这也呼应第 5 节：Agent 的可靠性本来就是个工程问题。
细节对比（版本、tool calling 写法、memory 实现、生产案例）在文档区 frameworks 逐篇展开。
5. Harness：从 Demo 到产品的距离
Harness（运行时脚手架/工程外壳） 是最容易被低估的一层：包裹在模型外面的全部工程设施。Demo 和可靠产品之间隔的不是更好的模型，而是更好的 Harness。
它的两种形态对应两类系统：
形态一：Coding Agent 的 Harness（以 Claude Code / OpenCode 为例拆解）
- 规则注入：AGENTS.md / CLAUDE.md 项目规则文件，每次请求注入 system prompt，让 Agent"入乡随俗"
- 工具最小权限：默认只给读工具，写/执行按需授权；每个工具的 description 就是给模型的 API 文档——工具描述写得含糊，模型就用得离谱
- Subagent 上下文隔离：探索类脏活（全库搜索）丢给子 Agent，只把结论带回主上下文，保护主窗口不被撑爆
- 验证闭环：让测试、lint、build 成为工具，模型改完自己跑、自己看报错、自己修——反馈信号比指令更有效
- 审批门与沙箱：破坏性动作（删除/推送/发布）必须人工批准，执行环境隔离
形态二：编排框架的 Harness（以 LangGraph / Spring AI Alibaba 的图机制为例）
- 图编排：把 Agent 流程显式化为状态图，节点=步骤，边=转移，比隐式的 prompt 指令可观测、可回放
- 状态管理与 Checkpoint：状态持久化，失败可恢复，支持时间旅行调试
- HITL（Human-in-the-Loop）：在关键节点中断等待人工审批后继续
- 可观测性：每一步的输入输出可追踪（对 Agent 调试是刚需，不是锦上添花）
一句话总结这一节：模型决定上限，Harness 决定下限。 用户感知到的"这 Agent 真好用/真拉胯"，大部分是 Harness 的差距。
6. 学习路径图
配套文档区：AI 学习地图，规划结构如下，随学习进度逐篇落地：
| 顺序 | 主题 | 对应本文章节 | 状态 |
|---|---|---|---|
| 1 | Agent 分类与架构模式 | §1 §2 | 规划中 |
| 2 | 执行循环逐环节拆解 | §3 | 规划中 |
| 3 | Tool Calling 机制 | §3 | 规划中 |
| 4 | Context 与 Memory | §3 | 规划中 |
| 5 | Java 框架对比（Spring AI / Spring AI Alibaba / LangChain4j） | §4 | 规划中 |
| 6 | Python 生态对照（LangChain / LangGraph） | §4 | 规划中 |
| 7 | Harness 概念与设计原则 | §5 | 规划中 |
| 8 | Coding Agent 拆解（Claude Code / OpenCode） | §5 | 规划中 |
| 9 | 编排框架机制（图编排 / HITL / Checkpoint） | §5 | 规划中 |
建议路径：先裸调 SDK 手写一遍 Agent Loop（步骤 2-3），再横向看框架（步骤 5-6），最后带着框架的困惑去看 Harness（步骤 7-9）——那时你会知道每一个机制都是在解决什么真实问题。