Skip to content
/

Atmosphere

atmosphere · Atmosphere/atmosphere · ★ 3.8k · last commit 2026-05-26

JVM framework for building production-grade governed AI agents with streaming transports, HITL approvals, Cedar/Rego policy admission, and durable workflow checkpoints.

Best whenEnterprise AI agents should behave like production services — with proper governance, durable state, real transports, and auditable policy decisions — not pr…
Skip ifprompt-only guardrails, stateless agent interactions without durable checkpoints
vs seeds
Atmosphere is categorically different from all 11 seeds. The seeds target developer AI assistants (Claude Code, Cursor) for coding…
Primitive shape 13 total
Subagents 12 Hooks 1
00

Summary

Atmosphere — Summary

Atmosphere is a JVM framework for building governed, streaming AI agents that need to behave like production services. It provides a single @Agent annotation that generates WebSocket/SSE/gRPC/WebTransport endpoints plus governance primitives (policy admission, human-in-the-loop approvals, cost ceilings, PII rewriting, admin kill switches), durable session management, and 12 runtime adapters (Spring AI, LangChain4j, Google ADK, Semantic Kernel, CrewAI, Koog, Embabel, etc.). The audit module (atmosphere-ai-audit-postgres) writes every governance decision to a JDBC table with full context snapshot. Policy modules support AWS Cedar and Rego (OPA) for deterministic admission control. The atmosphere.js SDK covers React, Vue, Svelte, React Native, and vanilla TS.

Compared to seeds: Atmosphere is architecturally distinct from all 11 seeds. The seeds are agent-harness methodologies or MCP tool servers for coding workflows; Atmosphere is a JVM streaming transport and governance framework for production customer-facing AI agents. The closest analogy would be Parlant (also focused on conversation governance for customer-facing agents) but Atmosphere operates at the transport/infrastructure layer (WebTransport, gRPC, WebSocket) while Parlant operates at the semantic/behavioral layer (guidelines, observations, journeys).

01

Overview

Atmosphere — Overview

Origin

Long-running Java/JVM project (2008-2026 per copyright notice), originally focused on real-time async web (WebSocket/SSE for Java). Re-positioned in 2025-2026 as an AI agent framework. Apache-2.0 licensed. 3,767 stars, 758 forks. Active.

Philosophy

"JVM runtime for streaming, governable AI agents. Declare behavior with @Agent — Atmosphere owns the transport, runtime dispatch, reconnect, authorization, observability, and governance path."

Atmosphere's bet: enterprises using JVM stacks (Spring Boot, Quarkus, Jetty) should be able to add AI agents without abandoning their existing infrastructure. The @Agent annotation makes an agent deployment look like any other service endpoint.

Core Positioning Statement

From the README: "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."

Key Design Decision: Not an Agent Platform

Atmosphere explicitly does NOT provide:

  • Compute/scheduling (your JVM host handles that)
  • Model hosting (calls providers; doesn't host weights)
  • Managed vector stores (use Spring AI's VectorStore or LangChain4j)
  • Scheduled execution / cron (use a dedicated scheduler)
  • Browser automation

This scoping is intentional — Atmosphere is a library, not a platform.

Fit vs. Alternatives

From README: "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 fit."

SKILL CARD Verification

Atmosphere ships SKILLCARD.yaml files per runtime adapter with OpenSSF Model Signing signatures (sigstore-keyless via .github/workflows/sign-skillcards.yml). Inspired by NVIDIA's verified-agent-skills catalog.

02

Architecture

Atmosphere — Architecture

Distribution

Maven Central: org.atmosphere:atmosphere-runtime and related modules. Also on npm: atmosphere.js.

<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-runtime</artifactId>
    <version>4.0.x</version>
</dependency>

CLI

brew install Atmosphere/tap/atmosphere
atmosphere run spring-boot-multi-agent-startup-team
atmosphere new my-agent --template ai-chat
atmosphere import https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

The atmosphere CLI creates new agent projects from templates and imports external skills.

Module System (Maven multi-module)

modules/
  cpr/              # atmosphere-runtime — core transport layer
  spring-boot-starter/  # Spring Boot 4.0 auto-configuration
  quarkus-extension/    # Quarkus 3.21+ integration
  ai/               # AgentRuntime SPI + built-in implementation
  ai-audit-kafka/   # Audit sink → Apache Kafka
  ai-audit-postgres/    # Audit sink → PostgreSQL
  ai-policy-cedar/  # AWS Cedar policy evaluator
  ai-policy-rego/   # OPA Rego policy evaluator
  a2a/              # A2A protocol support
  admin/            # Admin console
  admin-bundle/     # Bundled admin UI
  agent/            # @Agent annotation processing
  agentscope/       # AgentScope adapter
  agui/             # AG-UI protocol support
  anthropic/        # Anthropic runtime adapter
  benchmarks/       # Performance benchmarks
  channels/         # Communication channel adapters
  checkpoint/       # Durable workflow checkpoint store
  cohere/           # Cohere runtime adapter
  coordinator/      # @Coordinator + AgentFleet orchestration
  crewai/           # CrewAI adapter
  durable-sessions/ # Durable session SPI
  durable-sessions-redis/   # Redis durable sessions
  durable-sessions-sqlite/  # SQLite durable sessions
  embabel/          # Embabel adapter
  grpc/             # gRPC transport
  kafka/            # Kafka integration
  koog/             # Koog (Kotlin) adapter
  langchain4j/      # LangChain4j adapter
  mcp-client/       # MCP client
  mcp/              # MCP module
  rag/              # RAG support
  redis/            # Redis integration
  sandbox/          # Docker sandbox for code execution
  semantic-kernel/  # Microsoft Semantic Kernel adapter
  skills/           # Skill importation
  spring-ai/        # Spring AI adapter
  spring-ai-alibaba/    # Spring AI Alibaba adapter
  verifier/         # Response verification
  wasync/           # JVM async WebSocket client
  ...
atmosphere.js/      # TypeScript client library (React, Vue, Svelte, RN)

Required Runtime

  • JDK 21+
  • Maven (via ./mvnw wrapper)
  • Docker (for sandbox module)
  • Supported containers: Tomcat, Jetty, Netty, Undertow, Quarkus, Spring Boot

Target AI Tools

Spring AI, LangChain4j, Google ADK, Microsoft Semantic Kernel, AgentScope, CrewAI, Koog, Embabel, Spring AI Alibaba, Anthropic (direct), Cohere (direct). Framework-agnostic via AgentRuntime SPI.

03

Components

Atmosphere — Components

Core Annotations

Annotation Purpose
@Agent Declares a class as an AI agent; auto-registers endpoints + runtime
@Prompt Marks a method as the message handler
@Command Defines a slash command the agent responds to
@AgentScope Scopes agent execution (per-session, per-user, per-tenant)
@Coordinator Marks a coordinator that manages an AgentFleet

Runtime Adapters (12)

Each adapter ships a SKILLCARD.yaml with OpenSSF signature:

Adapter Module Language
Built-in modules/ai Java
Spring AI modules/spring-ai Java
LangChain4j modules/langchain4j Java
Google ADK modules/adk Java
Semantic Kernel modules/semantic-kernel Java
AgentScope modules/agentscope Java
CrewAI modules/crewai Java
Koog modules/koog Kotlin
Embabel modules/embabel Kotlin
Anthropic modules/anthropic Java
Cohere modules/cohere Java
Spring AI Alibaba modules/spring-ai-alibaba Java

Governance Primitives

Primitive Module/Class
Policy admission GovernancePolicy.evaluate()
Cedar policy ai-policy-cedar — AWS Cedar expression evaluation
Rego policy ai-policy-rego — OPA Rego evaluation
HITL approvals Durable hibernating approvals via REST surface
Cost ceilings Configurable per-session/tenant cost limits
PII rewriting Built-in PII redaction before logging
Admin kill switches Force-stop any running agent
Plan-and-verify Verification step before action execution

Audit Sinks

Module Storage
ai-audit-postgres JDBC → governance_audit_log table (PostgreSQL-optimized with JSONB)
ai-audit-kafka Apache Kafka audit event stream
GovernanceDecisionLog In-memory ring buffer (admin console)

Protocol Modules

Module Protocol
mcp MCP protocol support
a2a A2A protocol support
agui AG-UI protocol support
grpc gRPC streaming
channels Slack, Telegram, Discord, WhatsApp, Messenger

Memory

Module Backend
AiConversationMemory In-memory or durable (SQLite/Redis via ConversationPersistence SPI)
LongTermMemory InMemoryLongTermMemory, SqliteLongTermMemory, RedisLongTermMemory
SemanticRecallInterceptor BYO vector-store recall

Workflow

Module Purpose
durable-sessions Durable session SPI
checkpoint Durable Workflow<S> with per-step retry, JVM-restart resume
coordinator @Coordinator + AgentFleet handoffs and conditional routing

Developer Tools (Claude Code)

  • .claude/settings.json — Stop hook: check-drift-log.sh (blocks stop if drift correction language detected but .harness/drift-log.md not updated)
  • .claude/hooks/check-drift-log.sh — High-precision bash script checking for 6 drift-correction patterns in session transcript
  • .githooks/ — pre-commit, commit-msg, pre-push hooks (Apache 2.0 copyright headers, no AI co-author signatures)
05

Prompts

Atmosphere — Prompts

Atmosphere is a JVM framework. Its "prompts" are Java annotations and configuration code, not natural-language files. The most relevant prompt-like artifacts are the developer governance instructions.

AGENTS.md (Root — Developer Instructions)

## Build System: Maven

**This project uses Apache Maven with the Maven Wrapper (`./mvnw`).**

## Git Workflow

### Hooks Setup
**Run this at the START OF EVERY SESSION:**
git config core.hooksPath .githooks

**NEVER use `--no-verify` when committing or pushing.** The hooks enforce:
- Apache 2.0 copyright headers on all Java source files
- No unused or duplicate imports in staged Java files
- Commit message format (max 2 lines, conventional commits recommended)
- No AI-generated commit signatures
- Pre-push: Maven build must pass

### Commit Message Format
Use conventional commit prefixes. The commit-msg hook warns if missing:
type(scope): description

Rules enforced by hooks:
- Maximum 2 non-empty lines (summary + optional detail)
- First line under 100 characters
- NEVER add `Co-authored-by: Copilot` or any AI co-author trailer — the commit-msg hook will reject it
- Do not add ANY trailer lines (Co-authored-by, Signed-off-by, etc.) to commit messages

Prompting technique: Hard prohibition list with enforcement mechanism (git hooks). The explicit "NEVER add Co-authored-by" rule is a compliance policy preventing AI attribution footprints in commit history — unusual in the corpus.

.claude/hooks/check-drift-log.sh (Stop Hook)

# High-precision drift-correction patterns:
patterns=(
    'stale memory'
    '\boff-by-one\b'
    'I (was wrong|claimed)[^.]{0,120}(but|actual|truth)'
    'memor[a-z]+[[:space:]]+(was|is)[[:space:]]+(wrong|stale|out of date)'
    'fabricated[[:space:]]+(rule|stat|count|claim)'
    'verified by grep[^.]{0,60}(disagree|contradict|wrong|stale)'
)

# If drift-correction language detected but .harness/drift-log.md NOT updated:
{
  "decision": "block",
  "reason": "Drift correction language detected in session transcript, but 
   .harness/drift-log.md was not modified this session. Per feedback_drift_log.md,
   every caught drift gets a structured entry (date, claim, truth, slip path, gate added)
   appended in the same session."
}

Prompting technique: Meta-cognitive accountability enforcement. The Stop hook detects when an AI assistant acknowledged it was wrong (drift correction) but failed to document the error in the drift log. It blocks the session from ending and demands structured retrospection. This is a novel pattern — using lifecycle hooks to enforce epistemological accountability on the AI agent.

Cedar Policy (Runtime Governance)

permit (
    principal in Group::"support-agents",
    action == Action::"invoke",
    resource is Agent
)
when { context.business_tenant_id != "blocked-tenant" };

forbid (
    principal,
    action == Action::"invoke",
    resource == Agent::"finance-agent"
)
unless { principal in Group::"finance-cleared" };

Prompting technique: Declarative admit/deny policies in AWS Cedar language — deterministic, auditable, not LLM-based.

09

Uniqueness

Atmosphere — Uniqueness & Positioning

Differs from Seeds

Atmosphere occupies a unique position in the corpus: it is a JVM production framework for governed streaming agents, not a coding assistant methodology. The 11 seeds all target developer AI assistants (Claude Code, Cursor, etc.) helping humans write code; Atmosphere builds the AI agents that end-users interact with at runtime. The closest seed is none directly — Parlant (same batch) is also a runtime conversation governance framework but Python-based and semantic. Atmosphere's transport layer (WebTransport/HTTP3, gRPC, WebSocket, SSE) has no equivalent among seeds. Its Cedar/Rego policy engine, durable HITL approvals, and multi-adapter architecture are unique in the corpus.

Unique Characteristics

  1. Drift-log enforcement via Stop hook: The check-drift-log.sh Stop hook blocks session termination if the AI assistant acknowledged an error but didn't document it in .harness/drift-log.md. This is the most sophisticated meta-cognitive accountability enforcement in the corpus — using Claude Code lifecycle hooks to require retrospective documentation of AI mistakes.
  2. Cedar + Rego policy integration: Only framework in corpus integrating both AWS Cedar AND OPA Rego for agent admission control.
  3. SKILLCARD.yaml with OpenSSF signatures: Verifiable trust manifests for each runtime adapter, signed with sigstore-keyless. Inspired by NVIDIA's verified-agent-skills catalog.
  4. Durable HITL approvals with virtual thread parking: HITL gates that hibernate JVM virtual threads, persist state, and survive restarts — not a prompt asking the user to approve, but actual workflow pause/resume infrastructure.
  5. 12 runtime adapters with contract tests: More AI framework adapters than any other framework in the corpus. Each adapter has a contract test verifying capability flags.
  6. No AI co-author commit signatures: The commit-msg git hook explicitly rejects Co-authored-by: Copilot or any AI attribution. Unusual stance — most frameworks are indifferent to this.
  7. WebTransport/HTTP3 + gRPC: Real-time transport over modern protocols not available in any other AI agent framework in corpus.

Positioning

"Spring Boot for AI agents." Targets Java/Kotlin teams building production customer-facing agents who need enterprise governance (HITL, policy admission, audit trail) and multi-channel delivery (web, mobile, Slack, etc.) without switching off-JVM.

Observable Failure Modes

  • JVM-only: No Python, Go, or Rust clients. Hard adoption barrier for teams not on JVM.
  • Complexity: 40+ Maven modules. Understanding which modules to include requires significant study.
  • Long-lived connections: WebSocket/SSE session management at scale requires careful infrastructure tuning (load balancer sticky sessions, connection limits).
  • Policy author expertise: Cedar and Rego have steep learning curves. Organizations without existing Cedar/Rego expertise may find policy management harder than prompt-based guardrails.

Cross-References

  • Shares CNCF adjacent philosophy with AgentGateway
  • Drift-log pattern is novel — no similar mechanism observed in other frameworks
04

Workflow

Atmosphere — Workflow

Agent Development Workflow

Phase Artifact
Create project atmosphere new my-agent --template ai-chat
Add @Agent class Java class with @Prompt, @Command methods
Select runtime adapter --runtime spring-ai / --runtime langchain4j etc.
Configure governance GovernancePolicy with Cedar/Rego rules
Configure audit atmosphere-ai-audit-postgres + GovernanceDecisionLog
Add durable sessions durable-sessions-sqlite or durable-sessions-redis
Deploy Maven build → servlet container or Spring Boot jar

Governance Decision Flow

  1. Agent receives user message
  2. GovernancePolicy.evaluate() runs (Cedar/Rego/custom policy)
  3. If DENY: request rejected, audit record written
  4. If APPROVE: execution proceeds
  5. Tool call intercepted by policy (plan-and-verify or HITL gate)
  6. HITL: approval parks virtual thread, waits for REST endpoint confirmation
  7. Tool executes in sandbox (Docker) if configured
  8. Response passes through PII rewriter
  9. Audit record written to governance_audit_log + Kafka topic

Workflow Durable State

Start → Step 1 (result saved to checkpoint) 
     → JVM restart / failure
     → Resume from checkpoint → Step 2 → ... → End

No thread held while hibernated. Per-step retry on failure.

Multi-Channel Deployment

Same @Agent class can deliver over:

  • WebSocket
  • SSE (Server-Sent Events)
  • gRPC
  • WebTransport (HTTP/3)
  • Slack / Telegram / Discord / WhatsApp / Messenger (via channel adapters)
  • MCP (mcp-client module)
  • A2A (a2a module)
  • AG-UI (agui module)

Approval Gates

Gate Type Mechanism
HITL approval Durable hibernating approval via REST endpoint (/approve/:runId)
Plan-and-verify Agent generates plan, verifier evaluates before execution
Admin kill switch Force-stop via admin console
Cost ceiling Auto-block when per-session/tenant cost threshold exceeded
Policy admission Cedar/Rego policy denies request at admission time
06

Memory Context

Atmosphere — Memory & Context

Conversation Memory

AiConversationMemory — per-conversation message history. Two backends:

  • In-memory (default): lost on restart
  • Durable via ConversationPersistence SPI:
    • durable-sessions-sqlite module
    • durable-sessions-redis module

Long-Term Memory

LongTermMemory — per-user facts that persist across conversations. Three implementations:

  • InMemoryLongTermMemory
  • SqliteLongTermMemory
  • RedisLongTermMemory

Semantic Recall

SemanticRecallInterceptor — BYO vector-store integration. Retrieves relevant memories from a vector database before each turn. Atmosphere does not ship a vector store — uses Spring AI's VectorStore, LangChain4j embeddings, or user-provided implementation.

Durable Workflow State

Workflow with CheckpointStore:

  • Per-step state serialization
  • Resume across JVM restart (no thread held while hibernated)
  • Retry failed steps automatically
  • State files: SQLite or Redis (via checkpoint module)

Session Files

  • State in SQLite (durable-sessions-sqlite) or Redis
  • Audit records in PostgreSQL (governance_audit_log table with context_snapshot JSONB)
  • Audit events in Kafka topic (optional, ai-audit-kafka module)

Memory Persistence Scope

  • Session: AiConversationMemory — scoped per conversation
  • Global: LongTermMemory — per user, persistent across sessions
  • Workflow: Workflow<S> checkpoints — per workflow run, resume-capable

Context Compaction

No built-in compaction. Memory window management is delegated to the AgentRuntime adapter (Spring AI, LangChain4j, etc.) which each handle context limits differently.

Governance Audit Memory

The governance_audit_log table stores every governance decision with:

  • Timestamp
  • Policy name + version
  • Decision (permit/deny)
  • Reason
  • Evaluation latency (ms)
  • Full context_snapshot (JSONB) — the complete request context at decision time

This enables audit replay: any governance decision can be reconstructed from stored context.

07

Orchestration

Atmosphere — Orchestration

Multi-Agent Support

Yes — via @Coordinator and AgentFleet:

  • @Coordinator orchestrates multiple agents
  • AgentFleet manages a collection of agents with handoffs and conditional routing
  • Durable hibernating workflows coordinate multi-step multi-agent interactions

Orchestration Pattern

Hierarchical@Coordinator acts as the orchestrator dispatching to fleet agents. Also supports sequential chaining via Workflow<S>.

Execution Mode

Event-driven (servlet container) — Atmosphere runs inside your JVM container (Spring Boot, Quarkus, Jetty, etc.) and processes agent messages as async events. Long-lived WebSocket/SSE connections allow streaming.

Multi-Model Routing

Yes — 12 runtime adapters with contract-tested capability flags. The AgentRuntime SPI allows swapping the underlying LLM framework per agent. Each adapter advertises capabilities (tool calling, embeddings, streaming, structured output, prompt caching).

Model Role Mapping

No fixed role assignments. Different @Agent classes can use different runtime adapters (and thus different models). The coordinator routes to agents based on configuration, not model type.

Isolation Mechanism

Containeratmosphere-sandbox module provides a SandboxProvider SPI with DockerSandboxProvider as the default implementation. Code execution happens in isolated Docker containers.

Human-in-the-Loop

Durable HITL approvals:

  1. Approval gate reached → virtual thread parked (not blocked)
  2. Workflow state persisted to CheckpointStore
  3. REST endpoint available for human to approve/reject
  4. On approval: workflow resumes from checkpoint
  5. Survives JVM restarts — approval can come hours/days later

Coordination Journal

@Coordinator maintains a coordination journal recording: which agent handled each turn, handoff decisions, routing rationale, timing.

Plan-and-Verify

Before executing tool calls: the agent generates a plan, the verifier module evaluates the plan against policies, and only approved plans execute.

Consensus Mechanism

None — single coordinator, not distributed consensus.

08

Ui Cli Surface

Atmosphere — UI/CLI Surface

CLI Binary

Name: atmosphere Type: Project scaffolding and skill import CLI Install: brew install Atmosphere/tap/atmosphere or curl install.sh | sh Not thin wrapper — own runtime for project management

Subcommands:

  • atmosphere run <sample> — run a sample (e.g., spring-boot-multi-agent-startup-team)
  • atmosphere new <name> --template <template> [--runtime <adapter>] [--force] — create new project
  • atmosphere import <url> — import a skill from a URL

Local Web Dashboard

Admin Console: Ships via modules/admin and modules/admin-bundle. Admin console serves as the runtime observability and governance UI. No port specified in public docs (container-specific).

Features:

  • In-memory GovernanceDecisionLog ring buffer viewer
  • Running agents and session status
  • Admin kill switches (force-stop agents)
  • Cost ceiling monitoring
  • HITL approval queue

Client SDK — atmosphere.js

npm: atmosphere.js Targets: React, Vue, Svelte, React Native, vanilla TypeScript

Provides streaming WebSocket/SSE client for connecting browser applications to Atmosphere agents.

Observability

  • GovernanceDecisionLog: in-memory ring buffer for recent policy decisions (admin console)
  • ai-audit-postgres: governance_audit_log table with full context snapshots (JSONB)
  • ai-audit-kafka: Kafka topic for audit event streaming
  • SKILLCARD.yaml: Per-adapter trust manifest with OpenSSF Model Signing signatures

IDE Integration

Claude Code (developer tooling):

  • .claude/settings.json — Stop hook: check-drift-log.sh
  • .claude/hooks/check-drift-log.sh — 6-pattern drift-correction detector
  • .claude/CLAUDE.md — symlink to root AGENTS.md

No IDE plugin for end-users (not applicable — this is a server framework).

Development UX

./mvnw install -Pfastinstall    # Fast build
./mvnw test                     # Run tests
./mvnw checkstyle:checkstyle    # Checkstyle
git config core.hooksPath .githooks  # Enable git hooks (required at session start)

Template Library

Templates available via atmosphere new --template:

  • ai-chat — basic chat agent
  • ai-tools — agent with tool calling
  • (additional templates available for different runtime adapters)

Related frameworks

same archetype · same primary tool · same memory type

cc-spec-driven ★ 27

Tracks specification changes as CRs through a draft→confirm→RC→archive lifecycle with LLM-evaluated hooks that enforce checklist…

DevTeam: Claude Code Multi-Agent Dev System
Trellis ★ 8.5k

Team-scale AI coding harness: shared specs auto-injected via hooks into sub-agents across 14 AI tools, with per-developer…

ECC (Everything Claude Code) ★ 193k

Comprehensive harness-native operator system: 246 skills + 61 agents + continuous learning hooks + multi-model routing across 8…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…