https://github.com/atmosphere/atmosphere
The transport-agnostic real-time framework for the JVM. WebSocket, SSE, Long-Polling, gRPC, MCP — one API, any transport.
https://github.com/atmosphere/atmosphere
agentic-ai event-driven java mcp quarkus spring-boot sse streaming websocket
Last synced: 5 days ago
JSON representation
The transport-agnostic real-time framework for the JVM. WebSocket, SSE, Long-Polling, gRPC, MCP — one API, any transport.
- Host: GitHub
- URL: https://github.com/atmosphere/atmosphere
- Owner: Atmosphere
- License: apache-2.0
- Created: 2010-06-30T14:26:23.000Z (almost 16 years ago)
- Default Branch: main
- Last Pushed: 2026-03-27T03:19:22.000Z (10 days ago)
- Last Synced: 2026-03-27T07:46:42.424Z (10 days ago)
- Topics: agentic-ai, event-driven, java, mcp, quarkus, spring-boot, sse, streaming, websocket
- Language: Java
- Homepage: https://async-io.org/
- Size: 167 MB
- Stars: 3,745
- Watchers: 230
- Forks: 755
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-ChatGPT-repositories - atmosphere - Real-time transport layer for Java AI agents. Build once with @Agent — deliver over WebSocket, SSE, gRPC, MCP, A2A, AG-UI, or any transport. Works with Spring AI, LangChain4j, Google ADK, Embabel, Koog or the built-in OpenAI-compatible client. (The latest additions 🎉)
README
Atmosphere
Real-time transport layer for Java AI agents.
Build once with @Agent — deliver over WebTransport/HTTP3, WebSocket, SSE, gRPC, MCP, A2A, AG-UI, or any transport. 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.
## Quick Start
```bash
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 GitHub and run it
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:run
```
## `@Agent`
One annotation. The framework wires everything based on what's in the class and what's on the classpath.
```java
@Agent(name = "my-agent", description = "What this agent does")
public class MyAgent {
@Prompt
public void onMessage(String message, StreamingSession session) {
session.stream(message); // LLM streaming via configured backend
}
@Command(value = "/status", description = "Show status")
public String status() {
return "All systems operational"; // Executes instantly, no LLM cost
}
@Command(value = "/reset", description = "Reset data",
confirm = "This will delete all data. Are you sure?")
public String reset() {
return dataService.resetAll(); // Requires user confirmation first
}
@AiTool(name = "lookup", description = "Look up data")
public String lookup(@Param("query") String query) {
return dataService.find(query); // Callable by the LLM during inference
}
}
```
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 |
| (built-in) | Console UI at `/atmosphere/console/` |
## Key Features
**[Multi-Agent Orchestration](https://atmosphere.github.io/docs/agents/coordinator/)** — `@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](https://atmosphere.github.io/docs/reference/ai/)** — 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.
**[6 AI Runtimes](https://atmosphere.github.io/docs/reference/ai/)** — 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](https://atmosphere.github.io/docs/agents/a2a/)** — 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](https://atmosphere.github.io/docs/tutorial/23-channels/)** — Web, Slack, Telegram, Discord, WhatsApp, Messenger. Set a bot token and the same `@Command` + AI pipeline works everywhere.
**[Skill Files](https://atmosphere.github.io/docs/agents/skills/)** — Markdown system prompts with sections for tools, guardrails, and channels. Auto-discovered from classpath. Browse curated skills in the [Atmosphere Skills](https://github.com/Atmosphere/atmosphere-skills) registry.
**[Long-Term Memory](https://atmosphere.github.io/docs/agents/coordinator/)** — 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](https://atmosphere.github.io/docs/reference/ai/)** — Pluggable compaction strategies (sliding window, LLM summarization). Durable sessions via SQLite or Redis survive server restarts.
**[Eval Assertions](https://atmosphere.github.io/docs/reference/testing/)** — `LlmJudge` tests agent quality with `meetsIntent()`, `isGroundedIn()`, and `hasQuality()`. `StubAgentFleet` and `CoordinatorAssertions` for testing coordinators without infrastructure.
**[15 Event Types](https://atmosphere.github.io/docs/reference/ai/)** — `AiEvent` sealed interface: text deltas, tool start/result/error, agent steps, handoffs, approval prompts, structured output, routing decisions. Normalized across all runtimes.
**[5 Transports](https://atmosphere.github.io/docs/tutorial/04-transports/)** — WebTransport/HTTP3, WebSocket, SSE, Long-Polling, gRPC. Automatic fallback, reconnection, heartbeats, message caching. First Java framework with [WebTransport over HTTP/3](https://atmosphere.github.io/docs/webtransport/).
**[Observability](https://atmosphere.github.io/docs/reference/observability/)** — OpenTelemetry tracing, Micrometer metrics, AI token usage tracking. Auto-configured with Spring Boot.
## Client — atmosphere.js
```bash
npm install atmosphere.js
```
```tsx
import { useStreaming } from 'atmosphere.js/react';
function Chat() {
const { fullText, isStreaming, send } = useStreaming({
request: { url: '/atmosphere/agent/my-agent', transport: 'websocket' },
});
return
{fullText}
;
}
```
React, [Vue](atmosphere.js/README.md#vue), [Svelte](atmosphere.js/README.md#svelte), and [React Native](atmosphere.js/README.md#react-native) bindings available. For Java/Kotlin clients, see [wAsync](https://github.com/Atmosphere/wasync) — async WebSocket, SSE, long-polling, and gRPC client.
## Samples
| Sample | Description |
|--------|-------------|
| [startup team](samples/spring-boot-multi-agent-startup-team/) | `@Coordinator` with 4 specialist agents |
| [dentist agent](samples/spring-boot-dentist-agent/) | Commands, tools, skill file, Slack + Telegram |
| [ai-tools](samples/spring-boot-ai-tools/) | Framework-agnostic tool calling + approval gates |
| [orchestration-demo](samples/spring-boot-orchestration-demo/) | Agent handoffs and approval gates |
| [mcp-server](samples/spring-boot-mcp-server/) | MCP tools, resources, prompts |
| [rag-agent](samples/spring-boot-rag-chat/) | RAG with knowledge base search tools |
| [durable-sessions](samples/spring-boot-durable-sessions/) | SQLite/Redis session persistence |
[All 18 samples](samples/) · `atmosphere install` for interactive picker · [CLI reference](cli/README.md)
## Getting Started
```xml
org.atmosphere
atmosphere-spring-boot-starter
4.0.28
org.atmosphere
atmosphere-agent
4.0.28
```
Optional: `atmosphere-ai`, `atmosphere-mcp`, `atmosphere-a2a`, `atmosphere-agui`, `atmosphere-channels`, `atmosphere-coordinator`. Add to classpath and features auto-register.
**Requirements:** Java 21+ · Spring Boot 4.0+ or Quarkus 3.21+
## Documentation
[Tutorial](https://atmosphere.github.io/docs/tutorial/01-introduction/) · [Full docs](https://atmosphere.github.io/docs/) · [CLI](cli/README.md) · [Javadoc](https://atmosphere.github.io/apidocs/) · [Samples](samples/)
## Support
Commercial support and consulting available through [Async-IO.org](https://async-io.org).
## Companion Projects
| Project | Description |
|---------|-------------|
| [atmosphere-skills](https://github.com/Atmosphere/atmosphere-skills) | Curated agent skill files — personality, tools, guardrails |
| [javaclaw-atmosphere](https://github.com/Atmosphere/javaclaw-atmosphere) | Atmosphere chat transport plugin for JavaClaw |
## License
Apache 2.0 — @Copyright 2008-2026 [Async-IO.org](https://async-io.org)