Atmosphere/atmosphere · 上手攻略
- 仓库：
Atmosphere/atmosphere - 链接：https://github.com/Atmosphere/atmosphere
- 分类：AI Agent Runtime / JVM（Java）
- 作者：spark
- 更新：2026-08-31
数据速览（截至 2026-08-26 仓库公开计数）：3,796 stars · 760 forks · 4 contributors · Apache-2.0 · 主仓语言 Java（90%+）。⚠️ 主分支更新频次与版本号以仓库 Releases 页为准，本文不臆测具体小版本。
一、是什么
Atmosphere 是一个跑在 JVM 上的"实时 AI Agent 运行时"。把一句注解 @Agent 贴在普通 Java 类上，框架就会把这个类暴露成浏览器端点、MCP / A2A / AG-UI 端点，并把 LLM 的 token 流通过 WebSocket、SSE、long-polling、gRPC 实时推给前端。它不替代 Spring AI / LangChain4j / Semantic Kernel / Google ADK 等第三方 AI 框架，而是作为"服务层"把这些框架的产物包装成生产级实时端点：连接治理、鉴权、多租户、HITL 审批、会话回放、可观测性等。
二、解决什么问题
写一个能跑的 LLM 调用不难，把它变成"像生产服务一样"的 agent 端点很难——要管 WebSocket 重连、租户鉴权、工具调用前的策略准入、HITL 审批暂停/恢复、长会话的事件溯源回放。Atmosphere 把这层基础设施抽象为注解 + 模块化 classpath：
- 写一个
@Agent就同时拿到浏览器端点 + MCP / A2A / AG-UI 端点 + 命令行（/help、/status、/reset） +StreamingSession流式推送 - 想要换 AI 框架？换 classpath 上的
atmosphere-spring-ai/atmosphere-langchain4j/atmosphere-anthropic等模块即可，业务代码不动 - 想要多 Agent 协作？加
@Coordinator注解，得到delegate_task、task子代理派发、AgentFleet集群、事件溯源协调日志
三、快速安装
命令版本以仓库 README（main 分支）为准；Maven Central 的
org.atmosphere:atmosphere-runtime是底层运行时，CLI 是更轻的入口。
# 1) 安装 CLI（推荐）
brew install Atmosphere/tap/atmosphere
# 或一键脚本
curl -fsSL https://raw.githubusercontent.com/Atmosphere/atmosphere/main/cli/install.sh | sh
# 2) 起一个示例（多 Agent 创业团队 demo）
atmosphere run spring-boot-multi-agent-startup-team
# 3) 或从模板新建一个项目
atmosphere new my-agent --template ai-chat
cd my-agent
LLM_API_KEY=your-key ./mvnw spring-boot:run
切换后端 AI 框架：
# 默认是 built-in（OpenAI 兼容 HTTP 客户端）。要换 Spring AI：
atmosphere new my-agent --template ai-chat --runtime spring-ai
# 换 LangChain4j：
atmosphere new my-agent --template ai-tools --runtime langchain4j --force
四、核心用法
1. 一个最小的 @Agent
import org.atmosphere.agent.Agent;
import org.atmosphere.agent.Prompt;
import org.atmosphere.agent.Command;
import org.atmosphere.agent.AiTool;
import org.atmosphere.agent.Param;
import org.atmosphere.stream.StreamingSession;
@Agent(name = "my-agent", description = "What this agent does")
public class MyAgent {
@Prompt
public void onMessage(String message, StreamingSession session) {
session.stream(message);
}
@Command(value = "/status", description = "Show status")
public String status() { return "All systems operational"; }
@AiTool(name = "lookup", description = "Look up data")
public String lookup(@Param("query") String query) {
return dataService.find(query);
}
}
classpath 上加哪些模块，框架就自动注册哪些端点（README 表格）：
| 模块 | 自动注册的端点 / 能力 |
|---|---|
atmosphere-agent |
/atmosphere/agent/my-agent 浏览器端点、命令、/help |
atmosphere-mcp |
/atmosphere/agent/my-agent/mcp（MCP 2026-07-28 spec） |
atmosphere-a2a |
/atmosphere/agent/my-agent/a2a + Agent Card 发现 |
atmosphere-agui |
/atmosphere/agent/my-agent/agui |
atmosphere-channels |
Slack / Telegram / Discord / WhatsApp / Messenger 通道派发 |
atmosphere-admin |
管理控制台 + /api/admin/* |
2. Deep Agent 默认开启
一个裸 @Agent 在 README 里声称已默认开启 5 件套：长期记忆 + write_todos 计划 + 6 件套虚拟文件系统（ls、read_file、write_file、edit_file、glob、grep）+ 子代理派发（delegate_task / task）+ 提示词缓存 / skill / 大工具输出磁盘 offload。可用 @Agent(harness = {Harness.MEMORY}) 缩窄，或 harness = {} 退回裸循环；运行时真实状态在 /api/console/info 查询。
3. Runtime Adapter SPI
atmosphere-ai 提供 AgentRuntime SPI，内置 Built-in（OpenAI 兼容 HTTP 客户端）。其余适配器单独成模块，对接的版本号按 README 表格：
| 适配器 | 桥接框架 | Spring Boot | 关键能力 |
|---|---|---|---|
atmosphere-ai（Built-in） |
OpenAI 兼容 | 3.5 / 4.0 | 工具调用、JSON mode、视觉、音频、prompt caching、token 用量、原生重试 |
atmosphere-spring-ai |
Spring AI 2.0.0 | 4.0 | 工具调用、结构化输出、视觉、音频、prompt caching |
atmosphere-langchain4j |
LangChain4j 1.17.0 | 4.0 | 工具调用、结构化输出、视觉、音频、prompt caching |
atmosphere-adk |
Google ADK 1.5.0 | 4.0 | agent orchestration、工具调用、多模态、prompt caching |
atmosphere-koog |
JetBrains Koog 1.0.0 | 4.0 | agent orchestration、工具调用、多模态、prompt caching、取消 |
atmosphere-semantic-kernel |
Microsoft Semantic Kernel 1.5.0 | 4.0 | 工具调用、结构化输出、视觉、token 用量 |
atmosphere-anthropic |
Anthropic Messages API 原生 HTTP+SSE | — | 原生协议直连 |
atmosphere-cohere |
Cohere v2 chat 原生 HTTP+SSE | — | 原生协议直连 |
⚠️ 上表版本号引自 README 表格，未在 Maven Central 上逐一核对；落码前查仓库 pom.xml。
4. 会话回放（session tape）
docs/tutorial/36-session-tape 提供 SQLite 持久化的事件回放：记录 session 边界的 AI 事件，可在零模型调用下重建运行或协调树，再蒸馏成更小模型。生产事故排查直接用得上。
5. HITL 审批 + 治理
README 强调的"在关键路径上的策略准入"：policy admission、@AgentScope、人工审批、plan-and-verify、cost ceiling、PII 改写、admin kill switch。HITL 审批可以"durable hibernate"——挂起时不占线程，恢复通过 REST 审批端点。
五、典型适用场景
- 已有 Spring Boot / Quarkus / Netty 应用，要给业务系统加一个治理完备的 agent 端点
- 同时要把 agent 暴露给浏览器、Slack、Telegram、MCP 客户端、A2A 客户端等多端
- 需要持久化 HITL 审批、长任务休眠 / 恢复、会话回放
- 想换 AI 框架（Spring AI ↔ LangChain4j ↔ Semantic Kernel）但不想重写端点
六、坑与注意
- ⚠️ 主仓更新到 2026-08-26，但本文写作时（2026-08-31）未独立 web_fetch 校验所有 SPI 适配器版本；上表的"Spring AI 2.0.0 / LangChain4j 1.17.0 / ADK 1.5.0"等数字以 README 表格为准，实际 maven central 可能略有差异
- "Streaming + JVM + governance"是它的核心差异化卖点；如果你的 agent 是"无状态、短促、突发、自主休眠"，serverless 平台（Cloudflare Agents / Bedrock Agents / Vertex AI Agents）通常更合适
- 不要把它当成"完整 agent 托管平台"——README 自己说"Atmosphere ships the primitives your application uses at runtime; the host you choose (Tomcat / Jetty / Netty / Undertow / Quarkus / Spring Boot / servlet container) owns compute and scheduling"
- WebTransport / HTTP-3 不是默认开启，需要把
jetty-http3-server或reactor-netty-http放上 classpath + 配 dev cert atmosphere-sandbox默认是DockerSandboxProvider；浏览器自动化 / headless Chromium 不在它能力范围内- DeepAgent 默认 5 件套（记忆 + 计划 + 文件系统 + 子代理 + prompt cache）生产用够了，但要小心虚拟文件系统的边界——它是"会话作用域"，不能跨 agent 共享
七、与同类对比
| 维度 | Atmosphere | LangChain deepagents（Python） | Cloudflare Agents / Bedrock Agents / Vertex AI Agents |
|---|---|---|---|
| 运行时 | JVM（Java / Kotlin / Scala） | Python | Serverless 托管平台 |
| 流式传输 | WebSocket / SSE / long-polling / gRPC / WebTransport 全部 always-on | 应用层自己实现 | 平台托管 |
| AI 框架可替换 | 是（12 个 runtime adapter SPI） | 框架内耦合 | 一般不可替换 |
| 治理在关键路径 | 是（policy admission + PII 改写 + kill switch） | 需自己写 | 平台托管，部分受限 |
| 多协议暴露 | MCP / A2A / AG-UI / Slack / Telegram / Discord / WhatsApp / Messenger | 各自集成 | 一般只走平台原生 |
| HITL durable hibernate | 是 | 一般 in-process | 平台相关 |
| 本地自托管 | 是 | 是 | 否 |
八、一句话推荐结论
如果你的 agent 需要"长连接 + 多通道暴露 + 治理在关键路径 + AI 框架可热替换"这四件套同时满足，并且你已经在 JVM 栈里——Atmosphere 是当下选择面里最完整的一个。纯 Python 实验或 serverless 一次性任务，不值得为它换栈。