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

本文基于AgentScope Java 2.0.12026-09-02 GitHub Releases 核实的当前最新版编写框架 JDK 基线 17实战工程用 JDK 21模型为 DeepSeekOpenAI 兼容端点deepseek-chat。该领域迭代极快API 细节请以官方文档为准。开篇它自报家门的那一刻你 你是谁 agent 我是 **ginkgo**公司 IT 服务台的智能助手。 我用简洁的中文帮你处理各种 IT 求助——账号问题、软件安装、 网络故障、设备报修之类的事情。不知道的我不会瞎猜。 你 /reset [会话已重置上下文已清空] 你 你好 agent 你好我是 ginkgoIT 服务台助理。有什么我可以帮你的这是本文成稿当天我在自己机器的命令行里和一个 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-E08Graph 流程编排 → 角色权限 → 低置信度转人工进企业E09-E11企业 IM 接入 → 日志追踪与成本 → Docker 上线收官E12复盘框架教我的事后文提到的 E02、E09 都是这张地图上的站点比如 E09 就是进 IM那一集。本篇是第一块砖对话基座。14:05 建仓pom 里只多两行框架是 AgentScope Java——阿里 7 月 GA 的 Agent 框架2.0.0 GA 发布于 2026-07-102.0.1 是首个维护版2.0 把模型 provider 拆成了独立扩展包所以接入 DeepSeek走 OpenAI 兼容协议只需要两件dependencygroupIdio.agentscope/groupIdartifactIdagentscope-harness/artifactIdversion2.0.1/version/dependencydependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-model-openai/artifactIdversion2.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 构建完整代码见仓库此处只贴骨架OpenAIChatModelmodelOpenAIChatModel.builder().apiKey(config.apiKey()).baseUrl(config.baseUrl())// https://api.deepseek.com.modelName(config.modelName())// deepseek-chat.stream(true).build();HarnessAgentagentHarnessAgent.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 种事件之一后面做工具调用直播、人工审批时消费的是同一套FluxAgentEvent。第三段会话重置——没有专门 API就是换一个新的sessionId重建RuntimeContext。多轮上下文能自动保持靠的也是同一个RuntimeContext反复传入。配置外置单独说API Key 走环境变量 config/application.properties 内置默认三级优先真实配置文件加进.gitignore。拔掉 Key 启动输出的是操作指引而非堆栈——这是 PRD 里写死的验收标准也是给跟练读者的温柔[启动失败] 未找到模型 API KeyAgent 无法启动。请任选一种方式配置 1. 设置环境变量 DEEPSEEK_API_KEY 2. 复制 config/application.properties.example 为 config/application.properties填写 ginkgo.model.api-key15: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 散落下一集的工具注册就是第一个要硬核的地方。下集预告给它装上第一个工具E02 做工单查询让 Agent 能回答我的工单 1024 什么状态。这是它从会聊天到能干活的第一步——也是上一篇对比文里我特意标注以官方文档为准的 Toolkit 注册 API 的实战兑现版本差异如实记录。下集见。系列导航实战仓库本集全部代码已开源Giteelambert-ginkgo/ginkgo-agent对应dev-E01分支每集一个分支下集从本集合并历史里看得见每一步PRD 在仓库docs/下欢迎对照代码验证文章说的是不是真做了。公众号后台回复「手搓」获取系列合集。同一个 Agent用 Spring AI 2.0 和 AgentScope Java 各实现一遍差的不止代码量——系列前传零件 vs 整车的五维对照AgentScope Java 2.0 深度拆解阿里为什么用 Java 重写 Agent 框架——ReAct 内核与六大生产级能力测不住的 Agent 上不了线像写单测一样给 Agent 写 Evals——本系列 E10 可观测的预习课