Real-time transport layer for Java AI agents.
Build once with @Agent — deliver over any transport (WebSocket, SSE, WebTransport/HTTP3) and any protocol (gRPC, MCP, A2A, AG-UI). Works with Spring AI, LangChain4j, Google ADK, Embabel, JetBrains Koog, or the built-in OpenAI-compatible client.
Atmosphere is a transport-agnostic runtime for Java. Your application code declares what it does — the framework handles how it's delivered. A single @Agent class can serve browsers over WebSocket, expose tools via MCP, accept tasks from other agents via A2A, stream state to frontends via AG-UI, and route messages to Slack, Telegram, or Discord — all without changing a line of code.
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/ |
Multi-Agent Orchestration — @Coordinator manages a fleet of agents with parallel fan-out, sequential pipelines, conditional routing, coordination journal, and result evaluation. Test with StubAgentFleet — no infrastructure needed.
Agent Handoffs & Human-in-the-Loop — Transfer conversations between agents with session.handoff(). Pause tool execution with @RequiresApproval for human-in-the-loop approval — the virtual thread parks cheaply until the client approves or denies.
Durable HITL Workflows — CheckpointStore SPI persists agent workflow state as parent-chained snapshots with fork semantics. Pause workflows without holding a live thread; resume via REST or programmatic replay. Pairs with atmosphere-durable-sessions for streaming reconnect + workflow continuation.
6 AI Runtimes — Built-in, LangChain4j, Spring AI, Google ADK, Embabel, JetBrains Koog. Switch backends by changing one Maven dependency. All share tool calling, structured output, conversation memory, and usage tracking.
3 Agent Protocols — MCP (tools for Claude, Copilot, Cursor), A2A (agent-to-agent via JSON-RPC), AG-UI (streaming state to frontends). Auto-registered from classpath.
6 Channels — Web, Slack, Telegram, Discord, WhatsApp, Messenger. Set a bot token and the same @Command + AI pipeline works everywhere.
Skill Files — Markdown system prompts with sections for tools, guardrails, and channels. Auto-discovered from classpath. Browse curated skills in the Atmosphere Skills registry.
Long-Term Memory — Agents remember users across sessions. LongTermMemoryInterceptor extracts facts via LLM and injects them into future system prompts. Three strategies: on session close, per message, or periodic.
Conversation Memory — Pluggable compaction strategies (sliding window, LLM summarization). Durable sessions via SQLite or Redis survive server restarts.
Eval Assertions — LlmJudge tests agent quality with meetsIntent(), isGroundedIn(), and hasQuality(). StubAgentFleet and CoordinatorAssertions for testing coordinators without infrastructure.
15 Event Types — AiEvent sealed interface: text deltas, tool start/result/error, agent steps, handoffs, approval prompts, structured output, routing decisions. Normalized across all runtimes.
5 Transports — WebTransport/HTTP3, WebSocket, SSE, Long-Polling, gRPC. Automatic fallback, reconnection, heartbeats, message caching. First Java framework with WebTransport over HTTP/3 — auto-detected via AsyncSupport: native Jetty 12 QUIC connector (zero-config, no sidecar) or Reactor Netty HTTP/3 sidecar for Tomcat/Undertow. Self-signed cert for dev, Alt-Svc header advertisement, transparent fallback to WebSocket.
Authentication — TokenValidator + TokenRefresher SPIs with AuthInterceptor. Define a validator bean and connections without valid tokens are rejected at the WebSocket/HTTP upgrade. Auto-configured via Spring Boot.
Observability — OpenTelemetry tracing, Micrometer metrics, AI token usage tracking. Auto-configured with Spring Boot.
Admin Control Plane — Real-time dashboard at /atmosphere/admin/, 25 REST endpoints, WebSocket event stream, and MCP tools for managing agents, broadcasters, tasks, and runtimes. AI-manages-AI via MCP tool registration.
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.
| 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 |
All 20 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>4.0.31</version>
</dependency>
<!-- Agent module (required for @Agent, @Coordinator) -->
<dependency>
<groupId>org.atmosphere</groupId>
<artifactId>atmosphere-agent</artifactId>
<version>4.0.31</version>
</dependency>Optional: atmosphere-ai, 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+ or Quarkus 3.21+
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