LingShu 灵枢

The Pivot of Agent Orchestration

Engine, not OS. Open-source Java Agent Engine for JDK 8 syntax / JDK 17+ runtime enterprise stacks.
Built on a ReAct Loop with 9 pluggable SPI slots. MCP / SKILL.md / A2A-aligned. Spring AI-aligned. Spring Boot-native. Production-grade.

If your service already runs on JDK 17+ Spring Boot 3.x,
LingShu is the only Agent Engine that lives in your process — same JVM, same classpath, no new cluster.

Quick Start Star on GitHub

~/demo-fibonacci · lingshu run

$ lingshu run "用 Java 写一个并发安全的 LRU 缓存"
[step 1] ReasoningStarted : 需要 LinkedHashMap + ReentrantReadWriteLock
[step 1] Tool call        : file_write(LruCache.java)
[step 2] Observation      : 写入成功
[step 2] ReasoningStarted : 加单元测试
[step 2] Tool call        : file_write(LruCacheTest.java)
[step 3] Tool call        : shell_exec(mvn test)
[step 3] Observation      : Tests run: 5, Failures: 0
✓ 完成 · 共 3 步 · 总耗时 8.2s

⭐ Apache 2.0 ☕ JDK 17+ runtime 🌿 Spring Boot 🔌 MCP-ready 🧩 9 SPI slots

Why LingShu

A few sharp things we got right that the rest didn't.

JDK 8 Syntax, JDK 17+ Runtime

Source compiles to JDK 8 syntax — no sealed, no records, no var, no List.of. But ships to JDK 17+ runtimes (Spring Boot 3.2.x + Spring AI 1.x minimum). Best of both worlds.

9 SPI Slots

LlmProvider / Tool & ToolExecutor / Sandbox / SkillSource & Skill / SessionStore / Compactor / PromptBuilder / FlowEngine / A2aTransport. Every one swaps in via Provider SPI + one annotation.

ReAct, Not Magic

An agent is a loop — Thought → Action → Observation. LingShu makes the loop explicit, observable, and stoppable. No black boxes.

Two-layer Sandbox

PermissionPolicy at the model layer (block before LLM sees it). RuntimeSandbox at the system layer (chroot / seccomp / sysbox).

Skill as Tool

A SKILL.md file is the contract. LingShu parses it, registers a SkillTool, and exposes it to the LLM. Classpath + directory + git + MCP sources.

Adapter-friendly

Drop in GoogleAdkFlowEngine, AlibabaGraphFlowEngine, or your own DAG. Zero change to business code.

How LingShu stacks up

A side-by-side with the four projects that matter most in 2026.

	LingShu	OryxOS	Spring AI	LangChain
JDK baseline	✅ JDK 8 src / JDK 17+	⚠️ Java 21	⚠️ JDK 17	❌ Python
Form factor	✅ Embedded engine	⚠️ Distributed OS	✅ Embedded lib	✅ Lib
Deploy required	✅ None — in your JAR	⚠️ Separate K8s	✅ None	✅ None
SPI replaceability	✅ 9 slots	⚠️ partial	⚠️ partial	✅ via classes
Skill as Tool	✅ SKILL.md	✅ SKILL.md	❌	⚠️ via tools
MCP client	✅ built-in	✅ built-in	⚠️ alpha	⚠️ adapter
A2A protocol	✅ v1.0+ (Slot #9)	✅	❌	❌
ReAct Loop explicit	✅ 1st-class	✅	❌	⚠️ framework-side
FlowEngine replaceable	✅ SPI	❌ monolithic	❌	✅
License	Apache 2.0	Apache 2.0	Apache 2.0	MIT

LingShu's niche: the only Agent Engine targeting JDK 8 syntax / JDK 17+ runtime for enterprise Spring Boot stacks. Spring AI is integrated narrowly (LLM protocol + @Tool Schema only — see dsh §4.10.1) so we stay in control of the ReAct Loop & tool execution. OryxOS targets Java 21 with distributed deployment — different scale, different buyer.

Architecture

Nine slots. One loop. Swap anything.

                          ┌──────────────────────────────┐
                          │     FlowEngine  (Slot #8)     │
                          │ LinearTurnEngine · Google ADK │
                          └─────┬──────────────┬─────────┘
                                │ drives        │ emits events
                  ┌─────────────▼─────┐  ┌──────▼──────────┐
                  │  PromptBuilder #7 │  │  AgentEvent bus │
                  │  LlmProvider   #1 │  │  (Reactive)     │
                  └─────────────┬─────┘  └─────────────────┘
                                │
                  ┌─────────────▼──────────────┐
                  │   Tool + Skill Pool        │
                  │  #2 Tool/Executor · #4 Src │
                  └──────┬──────────────┬──────┘
                         │              │
                  ┌──────▼──────────────▼─────┐
                  │      Sandbox  (Slot #3)   │
                  │ permission + cmd + net    │
                  │ whitelist (chroot/seccomp)│
                  └──────┬────────────────────┘
                         │
                  ┌──────▼─────────────────────────────┐
                  │ SessionStore #5 + Compactor #6    │
                  │ A2aTransport #9 (external comms)  │
                  └───────────────────────────────────┘

ℹ️ Spring AI is used narrowly: LLM provider protocol conversion (OpenAI / Anthropic / Gemini / DeepSeek / Qwen / Kimi …) & @Tool JSON Schema generation only. The ReAct Loop & tool scheduling stay under our control — no Spring AI auto tool execution. See dsh §4.10.1 for the 3 hard rules.

1LlmProvider

2Tool / ToolExecutor

3Sandbox

4SkillSource / Skill

5SessionStore

6Compactor

7PromptBuilder

8FlowEngine

9A2aTransport

Plugin Architecture

Why Spring Boot SPI, not OSGi / ClassLoader isolation.

Spring Boot SPI chosen

Type-safe contracts. Typed Provider<T> + SlotRouter<P, T> catch errors at compile time.
Zero ClassLoader magic. No LinkageError, no CL leak, no cross-loader instanceof surprises.
AOT / native-image friendly. Spring Boot 3.2 path is mature; GraalVM native compiles cleanly.
Standard toolchain. IDE debugger, async-profiler, JFR all work as expected.

ClassLoader isolation considered

True isolation. Plugin crashes stay inside their own ClassLoader — the host JVM survives.
Multi-version coexistence. Plugin A uses Jackson 2.13, plugin B uses 2.15 — different ClassLoaders, no conflict.
Runtime install / uninstall. OSGi bundles can update live without a restart.
Trade-off: Metaspace leak risk, GraalVM-unfriendly, steep learning curve (OSGi 6 books), custom tooling required.

Why SPI wins for LingShu. Nine slots + Spring Boot + JDK 8 syntax / JDK 17+ runtime + single-tenant / single-trusted-source. ClassLoader isolation's 80% benefits go unused here; the cost (CL leak, LinkageError, GraalVM-unfriendly) is real. SPI's main weakness — version conflicts — is already mitigated by banned-dependencies enforcer + dependency:tree CI self-check + a minimal-dependency policy (dsh §10.1 + §17 R-13). Five abstractions are load-implementation-agnostic: Slot, SlotRouter, SlotResolver, Spring AI hard rules, R-13 three-pronged governance. If the trigger ever flips — open third-party marketplace, live hot-reload — the path forward is Pf4j-spring, not a rewrite. Full rationale in dsh §5.7 →

30-second Quick Start

Add a dependency. Annotate a class. Run an agent.

<dependency>
    <groupId>ai.lingshu</groupId>
    <artifactId>lingshu-core</artifactId>
    <version>0.1.0-alpha</version>
</dependency>

implementation 'ai.lingshu:lingshu-core:0.1.0-alpha'

import ai.lingshu.core.*;
import ai.lingshu.core.provider.anthropic.*;

@SpringBootApplication
public class MyFirstAgent {
    public static void main(String[] args) {
        SpringApplication.run(MyFirstAgent.class, args);
    }

    @Bean
    CommandLineRunner run(AgentFactory factory) {
        return args -> {
            Agent agent = factory.create(AgentConfig.builder()
                .flowEngine("linear")
                .llm(LlmConfig.builder()
                        .provider("anthropic")
                        .model("claude-sonnet-4-5")
                        .build())
                .build());

            RunResult r = agent.runBlocking("用 Java 写 Fibonacci");
            System.out.println(r.getFinalText());
        };
    }
}

agent:
  flow-engine: linear        # linear | google-adk | alibaba-graph
  llm:
    provider: anthropic
    model: claude-sonnet-4-5
    api-key: ${ANTHROPIC_API_KEY}
  sandbox:
    policy: strict           # strict | permissive
    runtime: chroot          # chroot | sysbox | seccomp | none
  max-steps:

Read full docs →