A framework for building streaming AI agents on the JVM. Atmosphere owns the transport layer — tokens flow from the LLM runtime to the client through a broadcaster you can filter, gate, and observe. @Agent declares the behavior; the framework handles streaming, tool calling, memory, reconnect, authorization, and cost accounting.
A @Agent class runs on any of seven AI runtimes (built-in OpenAI, Spring AI, LangChain4j, Google ADK, Embabel, JetBrains Koog, Microsoft Semantic Kernel) and is served over any of five transports (WebTransport/HTTP3, WebSocket, SSE, long-polling, gRPC) plus three agent protocols (MCP, A2A, AG-UI) and six channels (web, Slack, Telegram, Discord, WhatsApp, Messenger). Runtime and transport are swapped by changing a Maven dependency.
Atmosphere owns the broadcaster, which enables capabilities a pure orchestration library cannot provide: per-token PII rewriting in flight, per-tenant cost ceilings that block dispatch at the gateway, durable reconnect that replays mid-stream events after a client drop, triple-gate authorization on the admin control plane.
brew install Atmosphere/tap/atmosphere
# or
curl -fsSL https://raw.githubusercontent.com/Atmosphere/atmosphere/main/cli/install.sh | sh
# Run a built-in agent sample
atmosphere run spring-boot-multi-agent-startup-team
# Or scaffold your own project from a sample
atmosphere new my-agent --template ai-chat
# Import a skill from an allowed skills repo
atmosphere import https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
cd frontend-design && LLM_API_KEY=your-key ./mvnw spring-boot:runOne annotation. The framework wires everything based on what's in the class and what's on the classpath.
// Registers this class as an agent — auto-discovered at startup.
// Endpoints are created based on which modules are on the classpath:
// WebSocket, MCP, A2A, AG-UI, Slack, Telegram, etc.
@Agent(name = "my-agent", description = "What this agent does")
public class MyAgent {
// Handles user messages. The message is forwarded to whichever AI runtime
// is on the classpath (Spring AI, LangChain4j, ADK, etc.) and the LLM
// response is streamed back token-by-token through the session.
@Prompt
public void onMessage(String message, StreamingSession session) {
session.stream(message);
}
// Slash command — executed directly, no LLM call.
// Auto-listed in /help. Works on every channel (web, Slack, Telegram…).
@Command(value = "/status", description = "Show status")
public String status() {
return "All systems operational";
}
// confirm = "..." enables human-in-the-loop: the client must approve
// before the method body runs. The virtual thread parks until approval.
@Command(value = "/reset", description = "Reset data",
confirm = "This will delete all data. Are you sure?")
public String reset() {
return dataService.resetAll();
}
// Registered as a tool the LLM can invoke during inference.
// Also exposed as an MCP tool if atmosphere-mcp is on the classpath.
@AiTool(name = "lookup", description = "Look up data")
public String lookup(@Param("query") String query) {
return dataService.find(query);
}
}What this registers depends on which modules are on the classpath:
| Module on classpath | What gets registered |
|---|---|
atmosphere-agent (required) |
WebSocket endpoint at /atmosphere/agent/my-agent with streaming AI, conversation memory, /help auto-generation |
atmosphere-mcp |
MCP endpoint at /atmosphere/agent/my-agent/mcp |
atmosphere-a2a |
A2A endpoint at /atmosphere/agent/my-agent/a2a with Agent Card discovery |
atmosphere-agui |
AG-UI endpoint at /atmosphere/agent/my-agent/agui |
atmosphere-channels + bot token |
Same agent responds on Slack, Telegram, Discord, WhatsApp, Messenger |
atmosphere-admin |
Admin dashboard at /atmosphere/admin/ with live event stream |
| (built-in) | Console UI at /atmosphere/console/ |
| Capability | Module | Key types |
|---|---|---|
| Streaming transports | atmosphere-runtime |
WebTransport/HTTP3, WebSocket, SSE, long-polling, gRPC — negotiated via AsyncSupport; Jetty 12 QUIC native or Reactor Netty HTTP/3 sidecar |
| Agent declaration | atmosphere-agent |
@Agent, @Prompt, @Command, @AiTool, @RequiresApproval |
| AI runtimes | atmosphere-ai + atmosphere-{spring-ai,langchain4j,adk,koog,embabel,semantic-kernel} |
AgentRuntime SPI; capability matrix pinned in AbstractAgentRuntimeContractTest |
| Multi-agent coordination | atmosphere-coordinator |
@Coordinator, @Fleet, @AgentRef; parallel / sequential / conditional routing; coordination journal |
| Agent protocols | atmosphere-mcp, atmosphere-a2a, atmosphere-agui |
auto-registered endpoints per @Agent |
| Channels | atmosphere-channels |
Slack, Telegram, Discord, WhatsApp, Messenger dispatch from one @Command |
| Memory | atmosphere-ai |
sliding window, LLM summarization; durable via atmosphere-durable-sessions (SQLite / Redis) |
| Checkpoints | atmosphere-checkpoint |
CheckpointStore — parent-chained snapshots, fork, resume by REST |
| Reconnect & replay | atmosphere-durable-sessions + RunRegistry in atmosphere-ai |
clients reconnect with X-Atmosphere-Run-Id; AiEndpointHandler replays the mid-stream buffer to the new resource |
| Sandbox | atmosphere-sandbox |
Sandbox / SandboxProvider; Docker default (--network none, argv-form exec, strict mount); ServiceLoader for Firecracker / Kata / E2B / Modal |
| Authentication | atmosphere-runtime |
TokenValidator, TokenRefresher, AuthInterceptor — rejects at WebSocket / HTTP upgrade |
| Admin control plane | atmosphere-admin |
/atmosphere/admin/ UI, /api/admin/* REST, MCP tools; triple-gate (feature flag → Principal → ControlAuthorizer) |
| Flow viewer | atmosphere-admin |
GET /api/admin/flow — JSON graph keyed by coordinationId (nodes, edges, success / failure / avg duration) |
| Grounded facts | atmosphere-ai |
FactResolver SPI, per-turn; values escaped before prompt injection |
| Business tags | atmosphere-ai |
BusinessMetadata → SLF4J MDC (tenant, customer, session, event kind) |
| Guardrails | atmosphere-ai |
PiiRedactionGuardrail, OutputLengthZScoreGuardrail (tenant-partitioned), CostCeilingGuardrail |
| Stream-level PII rewrite | atmosphere-ai |
PiiRedactionFilter — BroadcasterFilter auto-installed on every present and future broadcaster when enabled; rewrites tokens before bytes flush to the client |
| Cost enforcement | atmosphere-ai |
CostCeilingAccountant bridges TokenUsage → CostCeilingGuardrail.addCost keyed by business.tenant.id; outbound @Prompt blocks once the tenant hits budget |
| Observability | atmosphere-runtime, atmosphere-ai |
OpenTelemetry spans, Micrometer metrics, token usage; BusinessMdcBenchmark pins the MDC hot-path cost |
| Permission modes | atmosphere-ai |
PermissionMode.DEFAULT / PLAN / ACCEPT_EDITS / BYPASS / DENY_ALL — runtime config, not redeploy |
| Evaluation | atmosphere-ai-test |
LlmJudge (meetsIntent, isGroundedIn, hasQuality); AbstractAgentRuntimeContractTest pins the capability matrix per runtime |
| Skill files | atmosphere-agent |
Markdown system prompts with tool / guardrail / channel sections; classpath-discovered |
The AI-runtime capability matrix — which runtimes ship tool calling, structured output, multi-modal input, prompt caching, embeddings, retry — lives in modules/ai/README.md and is enforced by AbstractAgentRuntimeContractTest.expectedCapabilities(), so the matrix and the runtime code cannot drift.
npm install atmosphere.jsimport { useStreaming } from 'atmosphere.js/react';
function Chat() {
const { fullText, isStreaming, send } = useStreaming({
request: {
url: '/atmosphere/agent/my-agent',
transport: 'webtransport', // HTTP/3 over QUIC
fallbackTransport: 'websocket', // auto-fallback
},
});
return <p>{fullText}</p>;
}React, Vue, Svelte, and React Native bindings available. For Java/Kotlin clients, see wAsync — async WebSocket, SSE, long-polling, and gRPC client, shipped in-tree.
| Sample | Description |
|---|---|
| startup team | @Coordinator with 4 A2A specialist agents |
| dentist agent | Commands, tools, skill file, Slack + Telegram |
| ai-tools | Framework-agnostic tool calling + approval gates |
| orchestration-demo | Agent handoffs and approval gates |
| chat | Room protocol, presence, WebTransport/HTTP3 |
| ai-chat | AI chat with auth, WebTransport, caching |
| mcp-server | MCP tools, resources, prompts |
| rag-chat | RAG with knowledge base search tools |
| a2a-agent | A2A assistant with weather/time tools |
| agui-chat | AG-UI framework integration |
| durable-sessions | SQLite/Redis session persistence |
| checkpoint-agent | Durable HITL workflow — @Coordinator + CheckpointStore + REST approval |
| ai-classroom | Multi-room collaborative AI |
| channels-chat | Slack, Telegram, WhatsApp, Messenger |
| personal-assistant | @Coordinator + AgentFleet over InMemoryProtocolBridge, @AiTool → crew dispatch, OpenClaw workspace |
| coding-agent | Docker Sandbox provider — clone, read, stream real file bytes to the client |
All samples · atmosphere install for interactive picker · atmosphere compose to scaffold multi-agent projects · CLI reference
<!-- Spring Boot 4.0 starter -->
<dependency>
<groupId>org.atmosphere</groupId>
<artifactId>atmosphere-spring-boot-starter</artifactId>
<version>${atmosphere.version}</version>
</dependency>
<!-- Agent module (required for @Agent, @Coordinator) -->
<dependency>
<groupId>org.atmosphere</groupId>
<artifactId>atmosphere-agent</artifactId>
<version>${atmosphere.version}</version>
</dependency>Optional: atmosphere-ai, atmosphere-spring-ai, atmosphere-langchain4j, atmosphere-adk, atmosphere-koog, atmosphere-embabel, atmosphere-semantic-kernel, atmosphere-mcp, atmosphere-a2a, atmosphere-agui, atmosphere-channels, atmosphere-coordinator, atmosphere-admin. Add to classpath and features auto-register.
Requirements: Java 21+ · Spring Boot 4.0.5+ or Quarkus 3.31.3+ · Current release: see the Maven Central badge above
Tutorial · Full docs · CLI · Javadoc · Samples
Commercial support and consulting available through Async-IO.org.
| Project | Description |
|---|---|
| atmosphere-skills | Curated agent skill files — personality, tools, guardrails |
| homebrew-tap | Homebrew formulae for the Atmosphere CLI |
| javaclaw-atmosphere | Atmosphere chat transport plugin for JavaClaw |
Apache 2.0 — @Copyright 2008-2026 Async-IO.org
