Atmosphere

The real-time engine for AI agents on the JVM. Tokens flow from the LLM runtime to the client through a broadcaster you can filter, gate, and observe — over WebSocket, SSE, long-polling, or gRPC, and out through MCP, A2A, and AG-UI. A plain @Agent is a full deep agent, batteries-included, and Atmosphere handles reconnect, authorization, and governance.

Atmosphere is built for teams that need AI agents to behave like production services: streaming over real transports, guarded before every tool call, observable by tenant and run, and portable across AI frameworks without rewriting the endpoint.

Why Atmosphere

Scope

Atmosphere is a real-time, event-driven framework, not an agent-hosting platform. We ship the primitives your application uses at runtime; the host you choose (Tomcat, Jetty, Netty, Undertow, Quarkus, Spring Boot, or any servlet container) owns compute and scheduling. Payment rails and commerce primitives are out of scope. Compared to the agent-platform stack vocabulary that has emerged around offerings like Cloudflare Agents, AWS Bedrock Agents, and Vertex AI Agents:

The differentiator is the streaming + JVM + governance combination: long-lived stateful agent sessions over real-time transports, with policy admission on the critical path. For stateless, bursty, autonomous agents that should hibernate when idle, a serverless agent platform is usually the better fit. For human-in-the-loop, multi-channel, governed agents inside an existing JVM stack, Atmosphere is the right fit.

Quick Start

Run a sample

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

Create an app

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

Swap the runtime adapter

# Built-in is the default. --runtime spring-ai scaffolds the app against the
# Spring AI adapter instead (a CLI overlay injects its Maven dependencies).
atmosphere new my-agent --template ai-chat --runtime spring-ai

# Use --force when a sample already pins a runtime adapter.
atmosphere new my-agent --template ai-tools --runtime langchain4j --force

Import a skill

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 declares the agent. Modules on the classpath decide which endpoints and integrations are registered.

@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";
    }

    @Command(value = "/reset", description = "Reset data",
             confirm = "This will delete all data. Are you sure?")
    public String reset() {
        return dataService.resetAll();
    }

    @AiTool(name = "lookup", description = "Look up data")
    public String lookup(@Param("query") String query) {
        return dataService.find(query);
    }
}

Deep agents, batteries-included

A plain @Agent is a deep agent out of the box. The harness defaults to the full set, so a bare annotation already carries:

• Memory — long-term facts recalled across sessions, plus conversation history with a compaction seam.
• A plan it maintains — the built-in write_todos tool (or a runtime's native plan surface), streamed to the client as it changes.
• A virtual filesystem — six bounded, conversation-scoped tools (ls, read_file, write_file, edit_file, glob, grep).
• Sub-agent delegation — on a @Coordinator, delegate_task for pre-declared fleet members and task to spawn an ephemeral, isolated sub-agent on demand.
• Prompt caching, skills, and large-tool-output disk offload — on by default, tuned by config.

Narrow the set per agent (@Agent(harness = {Harness.MEMORY})) or opt down to a bare loop (harness = {}); @AiEndpoint is opt-in. Every primitive reports its actual attached state at /api/console/info — runtime truth, never configuration intent. This is the same deep-agent capability set as LangChain deepagents, hosted by a JVM framework — see the comparison.

Terminology

Use provider for model vendors and runtime adapter for Atmosphere integrations. Not every runtime adapter exposes every capability.

AI Runtime Adapters

atmosphere-ai ships the AgentRuntime SPI plus the Built-in OpenAI-compatible adapter. Eleven additional adapters live in separate modules — nine wrap a third-party framework, and two (atmosphere-anthropic, atmosphere-cohere) are native HTTP+SSE clients for the Anthropic Messages API and the Cohere v2 chat API respectively. Drop one runtime adapter on the classpath and the same @Agent code dispatches through it.

Atmosphere does not replace these frameworks. You keep the native framework for what it does best — its models, tools, planners, memory, and vector stores — and Atmosphere adds the service layer around it: real-time transports, governance, HITL approval, durable sessions, replay, and MCP/A2A/AG-UI exposure. The adapter is a bridge, not a replacement; the Notes column below says which native framework each one is the best fit for.

Capabilities are intentionally not identical. The authoritative matrix is pinned by AbstractAgentRuntimeContractTest.expectedCapabilities(), so a runtime cannot drift from its declared feature set without breaking tests.

See the full capability matrix for text streaming, tool calling, structured output, system prompts, agent orchestration, conversation memory, tool approval, vision, audio, multi-modal, prompt caching, token usage, retry, passivation, and tool-call deltas.

Enterprise Controls

Atmosphere keeps governance on the critical path rather than as an afterthought.

Governance policy can be YAML-driven:

version: "1.0"
policies:
  - name: deny-destructive-sql
    type: deny-list
    config:
      phrases: ["DROP TABLE", "TRUNCATE", "DELETE FROM"]
  - name: tenant-cost-ceiling
    type: cost-ceiling
    config:
      ceilingDollars: 50.0

Or annotation-driven:

@AiEndpoint(path = "/support")
@AgentScope(
    purpose = "Customer support: orders, billing, store hours",
    forbiddenTopics = {"code", "programming", "medical advice"},
    onBreach = AgentScope.Breach.POLITE_REDIRECT)
public class SupportAgent { /* @Prompt method */ }

See the governance policy plane reference, governance docs, and spring-boot-ms-governance-chat sample.

Client Libraries

Install the TypeScript client:

npm install atmosphere.js

Use React, Vue, Svelte, React Native, or the low-level client directly:

import { useStreaming } from 'atmosphere.js/react';

function Chat() {
  const { fullText, isStreaming, send } = useStreaming({
    request: {
      url: '/atmosphere/agent/my-agent',
      transport: 'webtransport',
      fallbackTransport: 'websocket',
    },
  });

  return <p>{fullText}</p>;
}

For Java/Kotlin clients, use wAsync for async WebSocket, SSE, long-polling, and gRPC clients.

Flagship Samples

All samples · cli/samples.json · atmosphere install for the interactive picker.

Add Atmosphere to an App

<!-- Spring Boot 4.0 starter -->
<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-spring-boot-starter</artifactId>
    <version>${atmosphere.version}</version>
</dependency>

<!-- Agent module: @Agent, @Prompt, @Command, @AiTool -->
<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-agent</artifactId>
    <version>${atmosphere.version}</version>
</dependency>

Add only what you need:

• AI runtime: atmosphere-ai or one runtime adapter from the runtime table
• Protocols: atmosphere-mcp, atmosphere-a2a, atmosphere-agui
• Channels: atmosphere-channels
• Multi-agent: atmosphere-coordinator
• Admin/control plane: atmosphere-admin
• Plan-and-verify: atmosphere-verifier
• Sandbox: atmosphere-sandbox
• Durable sessions: atmosphere-durable-sessions plus atmosphere-durable-sessions-sqlite or atmosphere-durable-sessions-redis
• Checkpoints: atmosphere-checkpoint
• Audit sinks: atmosphere-ai-audit-kafka, atmosphere-ai-audit-postgres
• Policy engines: atmosphere-ai-policy-rego (OPA), atmosphere-ai-policy-cedar (AWS Cedar)

For Spring Boot 3.5 deployments, including Spring AI Alibaba, use atmosphere-spring-boot3-starter and build with -Pspring-boot3.

Requirements: Java 21+ · Spring Boot 4.1.0 or Spring Boot 3.5 via -Pspring-boot3 · Quarkus 3.36.3+ · current release from the Maven Central badge above.

Documentation

Tutorial · Full docs · CLI · Javadoc · Samples

Commercial Support

Production support tiers, compliance attestation, Microsoft Agent Governance Toolkit interop, plan-and-verify adoption, A2A v1.0.0 alignment, and legacy Atmosphere 2.x / 3.x long-term support are available from Async-IO. Book a 30-minute architecture call: async-io.live/contact.

Companion Projects

License

Apache 2.0 - Copyright 2008-2026 Async-IO.org