Atmosphere: a portable AI agent runtime for the JVM

The problem Atmosphere solves for JVM teams

Most Java teams wiring an LLM into a service end up writing the same plumbing twice. First they pick a framework: Spring AI, LangChain4j, Anthropic's SDK, or one of the others. Then they discover the endpoint, the reconnect handling, the authorization check and the approval step are all framework-specific, so swapping providers means rewriting the endpoint rather than the prompt. Atmosphere's answer is an AgentRuntime SPI that sits between your agent class and the provider. The README describes twelve runtime adapters with contract-tested capability flags, so the same @Agent class can run on Spring AI or LangChain4j without the transport layer noticing. The audience is narrow and specific: teams that already run Tomcat, Jetty, Netty, Undertow, Quarkus or Spring Boot and want the agent to behave like any other long-lived service in that container.

How the broadcaster pipeline and AgentRuntime SPI fit together

Tokens leave the LLM runtime and pass through a broadcaster that the documentation says you can filter, gate and observe. That broadcaster is the same pipeline regardless of transport: WebSocket, SSE, long-polling and gRPC are described as always-on defaults, with WebTransport over HTTP/3 optional and requiring either jetty-http3-server or reactor-netty-http on the classpath plus a development certificate. On the other side, the AgentRuntime SPI dispatches to the chosen provider, and the same agent can be exposed outward through MCP, A2A and AG-UI, plus channel adapters for Slack, Telegram, Discord, WhatsApp and Messenger. Governance sits on the critical path rather than beside it: policy admission, @AgentScope, plan-and-verify, PII redaction, cost ceilings and admin kill switches are all listed as runtime features. A plain @Agent is not a stub. The README states that memory, a plan via write_todos, a virtual filesystem and sub-agent delegation through task are on by default via the harness. That is a design choice with a cost: a minimal agent still carries the harness unless you turn parts off.

Installing Atmosphere and running a first sample

The README gives two install paths for the CLI. On macOS with Homebrew, the tap is Atmosphere/tap. Otherwise there is a shell installer served from the repository. After installing, the atmosphere run command takes a sample name; the README uses spring-boot-multi-agent-startup-team as its example.

brew install Atmosphere/tap/atmosphere

# Or:
curl -fsSL https://raw.githubusercontent.com/Atmosphere/atmosphere/main/cli/install.sh | sh

atmosphere run spring-boot-multi-agent-startup-team

To start a new project instead, atmosphere new takes a name and a template. The README's example uses the ai-chat template, then runs the generated Maven wrapper with an LLM_API_KEY environment variable. Expect the sample to start a Spring Boot application and stream tokens to a browser client over one of the default transports.

atmosphere new my-agent --template ai-chat
cd my-agent
LLM_API_KEY=your-key ./mvnw spring-boot:run

The CLI can also scaffold against a different adapter. The README shows --runtime spring-ai as an overlay that injects the adapter's Maven dependency into the generated project. If you prefer not to use the CLI at all, the runtime is published to Maven Central as org.atmosphere:atmosphere-runtime, and the repository keeps a bom/ directory, which is the usual sign that a bill of materials coordinates the module versions.

Where the design constrains you

The README is explicit that Atmosphere is a real-time, event-driven framework and not an agent-hosting platform. It does not host model weights; it calls providers. It does not do wall-clock scheduling; your container scheduler or a dedicated scheduler fires the workflow, and the durable Workflow<S> over CheckpointStore handles durable step execution instead. That split is honest but it means a team expecting a batteries-included platform will find gaps. Two more constraints are worth naming. WebTransport over HTTP/3 is optional and needs a specific server dependency plus a development certificate, so treat it as an upgrade path rather than a default. And the project's own scope statement says stateless, bursty, autonomous agents that should hibernate when idle are usually better served by a serverless agent platform. Payment rails and commerce primitives are declared out of scope. The harness being on by default is also a trade-off: sub-agent delegation and a virtual filesystem are useful, but they are surface area you inherit before you have decided you want it.

Atmosphere compared with Spring AI alone

Spring AI is one of the twelve adapters Atmosphere dispatches to, so this is not a like-for-like replacement. If you build directly on Spring AI, you get the model abstraction and the Spring integration, and you write the endpoint, the reconnect logic and the approval flow yourself. Atmosphere keeps Spring AI as the runtime but puts the broadcaster, the durable session store and the governance layer underneath it. The practical difference shows up in two places. Durable sessions and replay buffers mean a client that drops mid-stream can resume, which is work you would otherwise implement against your own session store. Durable HITL approvals hibernate without holding a thread and persist workflow state, resuming through REST approval surfaces. The cost of that is a larger dependency surface and a framework whose abstractions you now have to learn alongside Spring's. Teams that only need request-response calls to a model will find the broadcaster pipeline unnecessary weight.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent: atmosphere-4.0.70 landed on 2026-09-01, atmosphere-4.0.69 on 2026-08-30 and atmosphere-4.0.68 on 2026-08-23. That cadence is the main upgrade cost signal. A patch release roughly every week means you should pin versions through the bom/ module rather than floating them, and a MIGRATION.md at the repository root indicates the project documents breaking changes between versions. The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant. It also means no copyleft obligation attaches to your application code, though you should confirm how the optional modules you pull in are licensed rather than assuming the root licence covers everything. Nothing here is legal advice; check the licence files in the modules you actually depend on.

Editorial conclusion

Adopt Atmosphere if your agents already live in a JVM service and you need streaming transports, policy admission before tool calls and durable human approvals in the same process. Do not adopt it if your agents are stateless and bursty, or if you want the platform to host model weights and schedule wall-clock jobs; the README says serverless platforms fit better there. Before writing code, confirm which of the twelve adapters you need, whether your container is one of the listed hosts, and whether the CLI install path or the Maven artifacts fit your build.

Frequently asked questions

Official sources

1. Atmosphere/atmosphere on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases