AgentScope Java 从零（01）：2 个依赖、半天时间，跑通你的第一个 Agent-育师

本文基于AgentScope Java 2.0.1（2026-09-02 GitHub Releases 核实的当前最新版）编写，框架 JDK 基线 17+，实战工程用 JDK 21；模型为 DeepSeek（OpenAI 兼容端点，deepseek-chat）。该领域迭代极快，API 细节请以官方文档为准。

开篇：它自报家门的那一刻

你 > 你是谁 agent > 我是 **ginkgo**，公司 IT 服务台的智能助手。 我用简洁的中文帮你处理各种 IT 求助——账号问题、软件安装、 网络故障、设备报修之类的事情。不知道的我不会瞎猜。 你 > /reset [会话已重置，上下文已清空] 你 > 你好 agent > 你好！我是 ginkgo，IT 服务台助理。有什么我可以帮你的？

这是本文成稿当天，我在自己机器的命令行里和一个 Agent 的真实对话。它背后没有 Python、没有 Spring Boot、没有向量数据库——只有一个 Maven 工程、2 个依赖、五十来行 Java 代码。

这个系列不教"怎么用框架"——是把一个企业智能体从零养到上线的过程全公开：PRD、每一行代码、每一次报错、每一个架构决策。今天是第一集：2 个依赖、半天时间，命令行里跑通一个接入 DeepSeek 的真 Agent。

本篇你能做出什么

命令行里和接入 DeepSeek 的 Agent 多轮对话，回复逐字流出（打字机效果）
输入/reset随时清空上下文重开一局；拔掉 API Key 启动，看到的是人话提示而不是堆栈
全部代码在实战仓库ginkgo-agent的dev-E01分支，可对照复现（每集一个分支，下集从本集合并，历史里看得见每一步）

系列地图：「手搓企业智能体」十二集路线

这个系列要养的最终形态：一个 IT 服务台智能体——员工一句话描述问题，它完成理解、答复、建单、流转的全链路。整个系列的需求文档（PRD）公开在仓库里，十二集对应十一个功能模块（E12 是复盘）：

幕	集	养出什么
能对话、能干活	E01-E05	对话基座（本篇）→ 查工单工具 → 会话记忆 → 知识库问答 → 智能建单
像个产品	E06-E08	Graph 流程编排 → 角色权限 → 低置信度转人工
进企业	E09-E11	企业 IM 接入 → 日志追踪与成本 → Docker 上线
收官	E12	复盘：框架教我的事

后文提到的 E02、E09 都是这张地图上的站点（比如 E09 就是"进 IM"那一集）。本篇是第一块砖：对话基座。

14:05 建仓：pom 里只多两行

框架是 AgentScope Java——阿里 7 月 GA 的 Agent 框架（2.0.0 GA 发布于 2026-07-10，2.0.1 是首个维护版），2.0 把模型 provider 拆成了独立扩展包，所以接入 DeepSeek（走 OpenAI 兼容协议）只需要两件：

<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-harness</artifactId><version>2.0.1</version></dependency><dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-model-openai</artifactId><version>2.0.1</version></dependency>

一句话结论：harness 是整车（ReAct 循环、记忆、权限都在里面），openai 扩展包是发动机适配器——2 个依赖就是全部，没有 starter、没有父 pom 继承。选题时我标题草稿写的是"3 个依赖"，实测只有 2 个，标题按实改——这个系列的规矩是数字必须真实。

14:20 第一个报错：不是代码的错，是 JDK 的

mvn compile迎面一句：无效的目标发行版：21。

原因没任何技术含量：本机默认 JDK 停在 17，而工程 pom 写的是 21。官方 README 明确框架基线是 JDK 17+，所以 17 本来也能用——是我自己的工程骨架定了 21，那就指过去：

JAVA_HOME=$(/usr/libexec/java_home-v21)mvn compile

一句话结论：报错先读全半句再慌——"无效的目标发行版"从来不是框架问题，是 javac 版本够不着 target。这个坑不值钱，但每个跟练的人都会踩到，如实记下。

14:35 第二个报错：Maven 仓库里躺着两个坏 jar

编译再次失败，这次报错长这样：zip END header not found——传递依赖里的opentelemetry-instrumentation-api和sqlite-jdbc两个 jar 下载损坏，本地仓库里躺着 0 字节残骸。这个报错跟代码无关、跟框架也无关，纯属本地仓库事故，但它出现在编译期，会伪装成依赖问题精准浪费你十分钟。

修法一句话：删掉本地仓库里这两个 artifact 目录，mvn compile重新下载，编译通过。

一句话结论：Maven 对"文件存在"的信任是盲目的——它只认文件在不在，不认文件坏没坏；遇到 zip 类报错，删了重下是唯一正解。

15:00 五十行代码：Agent 跑起来

核心代码三段。第一段，模型与 Agent 构建（完整代码见仓库，此处只贴骨架）：

OpenAIChatModelmodel=OpenAIChatModel.builder().apiKey(config.apiKey()).baseUrl(config.baseUrl())// https://api.deepseek.com.modelName(config.modelName())// deepseek-chat.stream(true).build();HarnessAgentagent=HarnessAgent.builder().name("ginkgo-service-desk").sysPrompt("你是企业 IT 服务台智能体 ginkgo……").model(model).workspace(Path.of(".agentscope","workspace")).build();

一句话结论：HarnessAgent是框架给的现成整车——Builder 填完参数，ReAct 循环、记忆、状态落盘已经全在里面；workspace指定后，会话状态自动按(userId, sessionId)隔离落盘。

第二段，对话循环里的流式输出：

agent.streamEvents(newUserMessage(input),ctx).doOnNext(event->{if(event.getType()==AgentEventType.TEXT_BLOCK_DELTA){System.out.print(((TextBlockDeltaEvent)event).getDelta());}}).blockLast();

一句话结论：AgentScope 的流式不是 token 流而是事件流——文本增量只是 31 种事件之一，后面做工具调用直播、人工审批时，消费的是同一套Flux<AgentEvent>。

第三段，会话重置——没有专门 API，就是换一个新的sessionId重建RuntimeContext。多轮上下文能自动保持，靠的也是同一个RuntimeContext反复传入。

配置外置单独说：API Key 走"环境变量 >config/application.properties> 内置默认"三级优先，真实配置文件加进.gitignore。拔掉 Key 启动，输出的是操作指引而非堆栈——这是 PRD 里写死的验收标准，也是给跟练读者的温柔：

[启动失败] 未找到模型 API Key，Agent 无法启动。请任选一种方式配置： 1. 设置环境变量 DEEPSEEK_API_KEY 2. 复制 config/application.properties.example 为 config/application.properties，填写 ginkgo.model.api-key

15:40 一个差点背上的 Spring Boot

代码跑到一半，我停下来问了自己一个问题：“是不是直接用 Spring Boot 更方便一点？”——配置体系白捡、DI 现成、读者也熟，反正后面 IM 接入也得要 HTTP。认真盘算之后的决策是不引，留到 E09——理由三条：

本集验证入口是命令行，Spring Boot 的 DI/Web 优势在 CLI 场景几乎为零，纯属先背上；
标题承诺"2 个依赖"，引入 starter 后数字就站不住了；
真正需要 HTTP 的地方是 E09 的 IM 回调（钉钉/企微/飞书的 webhook + 签名鉴权）——需求驱动框架进场，届时无论手搓@Bean还是接官方 starter，都是小工程，迁移成本近零。

这个决策连同依据写进了 PRD 的决策记录（第 9 节，编号 Q6）。这个系列里每个架构选择都会这样留痕——你可以拿着 PRD 对照代码，验证"文章里说的是不是真做了"。

本集判断

跑通第一天的真实感受：AgentScope Java 的"整车感"从第一行代码就成立了。streamEvents()一套事件流把"打字机"和未来的"工具直播、审批流"统一了；RuntimeContext强制传入(userId, sessionId)，把"多用户多会话隔离"从第一天就焊死在 API 上——不是后期补丁，是入口设计。

也要说实话：今天只摸到了它 10% 的面——工具注册、记忆策略、权限引擎都还没动，文档站的 API 细节比 README 散落，下一集的工具注册就是第一个要硬核的地方。