Runtime Selection

Atmosphere ships twelve AgentRuntime adapters. Every adapter implements the same Java SPI, so switching between them is a one-line Maven dependency swap — but each one wraps a different upstream agent framework with different strengths. This page is the decision tree to walk before picking, and the per-runtime “when to pick” notes once you have.

Source of truth. The capability flags quoted below come straight from .harness/capabilities.snapshot.json, regenerated by scripts/regen-capability-snapshot.sh and pinned by CapabilitySnapshotTest. The matrix cannot drift from the running code without breaking the build (Correctness Invariant #5 — Runtime Truth). See the AgentRuntime capability matrix for the full table.

Decision tree

Walk these questions in order; stop at the first match.

1. New to Atmosphere AI and just need it to work? → Built-in (atmosphere-ai). Zero extra deps, OpenAI-compatible client out of the box, one of two runtimes (with Cohere) that emit TOOL_CALL_DELTA for token-streaming tool-call argument deltas. Use --model / LLM_API_KEY to point at OpenAI / Gemini / Ollama / any compatible endpoint.

2. Already on Spring Boot with Spring AI’s ChatClient / VectorStore SPIs elsewhere? → Spring AI (atmosphere-spring-ai). Reuses your Spring AI provider abstraction, threads Content.Image / Content.Audio into Spring AI Media, honors prompt_cache_key on the OpenAI path.

3. Non-Spring JVM stack (plain Spring Framework, Quarkus, Micronaut, Vert.x) and want a vendor-neutral LLM / embedding / tool API? → LangChain4j (atmosphere-langchain4j). Largest ecosystem of vendor adapters, multi-modal vision / audio / image, OpenAI prompt cache, embedding-store retriever bridge.

4. Gemini-native execution with Google’s agent topology (sub-agents, ContextCacheConfig, ReAct over Vertex AI)? → Google ADK (atmosphere-adk). Only runtime declaring AGENT_ORCHESTRATION from a hosted vendor; native vision / audio / prompt-caching against Gemini.

5. Kotlin shop with JetBrains’ coroutine-first agent framework and native cancellation? → Koog (atmosphere-koog). Only runtime declaring CANCELLATION natively (AIAgent.cancel() propagates from StreamingSession.isCancelled()); Bedrock prompt-cache control; coroutine-cancel + JNI interrupt + Reactor dispose all wired through executeWithHandle.

6. Goal-graph multi-agent work (Embabel’s @Agent declarative planner)? → Embabel (atmosphere-embabel). Goal-graph orchestration, Spring AI provider underneath, tool bridge layered through Embabel’s own Tool.Handler so @RequiresApproval gates still fire.

7. Microsoft Semantic Kernel plugin / planner ecosystem (.NET-equivalent surface on the JVM)? → Semantic Kernel (atmosphere-semantic-kernel). SK 1.5 surface with KernelFunction tool bridge through Atmosphere’s ToolExecutionHelper, sidecar bridge for per-request InvocationContext / KernelHooks.

8. Alibaba’s AgentScope reasoning loop (Qwen-native ReAct, Alibaba Cloud AI Studio)? → AgentScope (atmosphere-agentscope). Reactor-backed streaming, AgentScopeToolBridge for portable @AiTool calls, the second runtime declaring native CANCELLATION (Reactor subscription cancellation on every event tick).

9. Spring AI Alibaba’s ReactAgent graph and Alibaba Cloud DashScope models on Spring Boot 3? → Spring AI Alibaba (atmosphere-spring-ai-alibaba). Buffered streaming (the upstream ReactAgent.call() returns a single AssistantMessage); Atmosphere still streams that buffered reply over WebSocket / SSE; TOKEN_USAGE works via the UsageCapturingChatModel decorator threaded into auto-config. Pin Spring Boot 3 today — Alibaba 1.1.2.2 hardcodes Spring AI 1.1.x types.

10. Anthropic Messages API directly, without going through Spring AI / LangChain4j? → Anthropic (atmosphere-anthropic). Native HTTP+SSE client against the Anthropic Messages API — no third-party SDK on the classpath. Tool loop capped at five rounds, cancellation-aware. Configure via anthropic.api.key system property or ANTHROPIC_API_KEY environment variable; custom headers (Helicone-Auth, tenant IDs, tracing) passthrough with reserved-header filtering.

11. Cohere v2 chat API directly, without going through Spring AI / LangChain4j? → Cohere (atmosphere-cohere). Native HTTP+SSE client against POST /v2/chat — no third-party SDK on the classpath. Tool dispatch routes through ToolExecutionHelper.executeWithApproval. Configure via cohere.api.key system property or COHERE_API_KEY environment variable; declares VISION + MULTI_MODAL natively.

If multiple options match, pick the lowest-numbered one — the runtimes are ordered from “most-general / most-portable” at the top to “most-specialized” at the bottom.

Quick comparison

Runtime	Best for	Streaming	Tool calling	Embeddings
Built-in	Default; OpenAI-compatible endpoints; zero extra deps	Token-by-token	✅ + TOOL_CALL_DELTA	✅
Spring AI	Spring Boot apps; existing Spring AI VectorStore in scope	Token-by-token	✅	✅
LangChain4j	Vendor-neutral JVM (Quarkus, Micronaut, Vert.x)	Token-by-token	✅	✅
Google ADK	Gemini-native + sub-agent orchestration	Token-by-token	✅ + AGENT_ORCHESTRATION	—
Embabel	Goal-graph planner workflows	Token-by-token	✅ + AGENT_ORCHESTRATION	✅
Koog	Kotlin coroutine + native CANCELLATION	Token-by-token	✅ + AGENT_ORCHESTRATION + CANCELLATION	✅
Semantic Kernel	Microsoft / .NET ecosystem parity on JVM	Token-by-token	✅	✅
AgentScope	Qwen-native ReAct, Alibaba Cloud AI Studio	Token-by-token	✅ + CANCELLATION	—
Spring AI Alibaba	DashScope / ReactAgent graph on Spring Boot 3	Buffered (one chunk + complete)	✅	✅
Anthropic	Direct Anthropic Messages API, no third-party SDK	Token-by-token	✅ + PER_REQUEST_RETRY (five-round tool loop, cancellation-aware)	—
Cohere	Direct Cohere v2 chat API, no third-party SDK	Token-by-token	✅ + VISION + MULTI_MODAL	—

What’s the same on every runtime

Some capabilities are declared by every adapter because Atmosphere implements them once in the pipeline layer or in AbstractAgentRuntime — the adapter only plugs in where it differs:

• TEXT_STREAMING (every runtime; Spring AI Alibaba is buffered)
• SYSTEM_PROMPT (every runtime)
• STRUCTURED_OUTPUT (every runtime — pipeline wraps the session in StructuredOutputCapturingSession with system-prompt schema injection)
• CONVERSATION_MEMORY (every runtime — AbstractAgentRuntime.assembleMessages threads context.history() into the outgoing message list)
• TOOL_CALLING / TOOL_APPROVAL (every runtime — each ships a tool bridge that routes through ToolExecutionHelper.executeWithApproval)
• TOKEN_USAGE (every runtime — Spring AI Alibaba captures via the UsageCapturingChatModel decorator)
• PER_REQUEST_RETRY (every runtime — executeWithOuterRetry baseline plus the upstream native retry layer)
• BUDGET_ENFORCEMENT (every runtime — wall-clock + token / step budgets honored uniformly)
• CONFIDENCE_SCORES (every runtime — pipeline parses {"confidence": …} field on stream completion)
• PASSIVATION (every runtime — AgentPassivation snapshots context.history() into a CheckpointStore)

Swapping runtimes via the CLI

The Atmosphere CLI handles the swap mechanically:

# Build a chat sample on the built-in runtime first
atmosphere new my-app --template ai-chat --runtime builtin

# Later, switch the same sample to Spring AI (one-line Maven dep change
# applied to the scaffold's pom.xml)
atmosphere new my-app --template ai-chat --runtime spring-ai --force

--runtime accepts builtin, spring-ai, langchain4j, adk, embabel, koog, semantic-kernel, agentscope, spring-ai-alibaba. The --force flag wipes any existing adapter dependency declared in cli/runtime-overlays.json from the scaffolded pom.xml before injecting the chosen overlay — required for samples that already pin a non-default adapter.

Samples whose Java code imports provider-specific types directly (e.g. OpenAiStreamingChatModel) still need manual edits after a force-swap; the transparent templates (ai-chat, multi-agent, etc.) work end-to-end with no code changes.

Add --routing to scaffold the opt-in, config-driven model router:

atmosphere new my-app --template ai-chat --routing

This appends a commented, ready-to-uncomment atmosphere.ai.routing.* block to the generated application.yml (off by default; the scaffold is byte-identical until you uncomment it). It is only valid for AI templates that ship an application.yml. The four rule families (content / model / cost / latency) and their compose order are documented in the AI reference.

Source

• Module README: modules/ai/README.md