Skip to content

README.md

Latest commit

 

History

History
224 lines (156 loc) · 8.64 KB

README.md

File metadata and controls

224 lines (156 loc) · 8.64 KB
Raw

openJiuwen Agent Runtime Java

中文版 | English Version

Introduction

openJiuwen Agent Runtime Java (agent-runtime-java) is the Java implementation repository for Agent Distributed Runtime (the large Runtime box in the architecture diagram). service/ is the Agent Server slice inside that Runtime — currently the main delivered module: Spring Boot HTTP ingress, in-process A2A, Adapters, and Agent Core via Maven.

Agent Core lives in agent-core-java. Agent Runtime Manager is planned under manager/* in this same repo. Python is a peer Runtime implementation (Agent Server often on FastAPI / Yuanrong FaaS).

See Scope & roadmap and Logical Architecture (Chinese).

Why Agent Runtime Java?

  • Minimal path to HTTP: Spring Boot auto-configures controllers, orchestrator, lifecycle hooks, and probes — you mainly provide or select an AgentHandler.

  • Cross-language alignment: POST /v1/query (SSE), POST /v1/reset_conversation, GET /health — same routes and semantics as Python AgentApp for gateway routing and migration.

  • In-process A2A: Agent Card, JSON-RPC (SendMessage / SendStreamingMessage), TaskStore, and remote-agent delegation without a separate A2A platform process.

  • Clear module boundaries: spec (contracts & SPI) → adapters (execution engine, middleware, external egress) → app (Ingress + Orchestrator) — one-way dependencies for custom images.

Quick Start

Requirements

  • OS: Windows, Linux, macOS.
  • Java: 17+.
  • Build: Maven 3.9+.
  • agent-core-java: see root pom.xml (agent-core.version / agent-core.git.branch). Local build: [Agent Core dependency](documents/zh/2.开发指南/Agent Core 依赖.md).

Build from Source

git clone https://gitcode.com/openJiuwen/agent-runtime-java.git
cd agent-runtime-java
mvn clean install -DskipTests

Run Tests

From the service directory:

cd service
mvn clean test

Run the Demo

Default mock handler, port 8090:

cd service
mvn -pl agent-service-demo -am spring-boot:run

Non-streaming query:

curl -s http://localhost:8090/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"conversation_id":"demo-c1","message":"hello","stream":false}'

Expected in mock mode: {"result":{"content":"demo:hello",...}}.

Streaming query (SSE):

curl -N -s http://localhost:8090/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"conversation_id":"demo-c1","message":"hello","stream":true}'

Agent Card (A2A):

curl -s http://localhost:8090/.well-known/agent-card.json

More examples (LLM mode, custom handlers, MCP/A2A samples): service/agent-service-demo/README.md.

Use as a Maven Dependency

<dependency>
    <groupId>com.openjiuwen</groupId>
    <artifactId>agent-service-app</artifactId>
    <version>0.1.0</version>
</dependency>
<dependency>
    <groupId>com.openjiuwen</groupId>
    <artifactId>agent-service-adapters-agentcore</artifactId>
    <version>0.1.0</version>
</dependency>

Provide a @Bean AgentHandler or set openjiuwen.service.agent-id for the default Core handler.

Architecture

Agent Runtime Java maps to Agent Distributed Runtime (Java) in the architecture diagram; service/ maps to Agent Server inside it.

Middleware (Redis…)  →  Runtime (this repo) · Agent Server (service/)  →  External (LLM, MCP, A2A…)
Logical component In agent-runtime-java Status
Agent Distributed Runtime repo root ✅ Java carrier (expanding)
Agent Core Maven agent-core-java ✅ dependency
Agent Server service/* ✅ main delivery today
In-process A2A agent-service-app ✅
Agent Runtime Manager manager/* ⏳ planned in this repo
Platform A2A gateway applications/* or external ⏳ / 🔌

Deep dive (Chinese): Logical Architecture, Architecture Overview.

HTTP query call chain:

HTTP Controller → ServeOrchestrator → AgentHandler → Core Runner

A2A call chain (when enabled):

A2A Client → Agent Card / JSON-RPC → A2AProtocolAdapter → ServeOrchestrator → AgentHandler → Runner

Controllers must not bypass the orchestrator to call Runner directly.

Features

Agent Service (HTTP Ingress)

  • Query: POST /v1/query, POST /query (legacy), POST /v1/query/reactive (WebFlux).
  • Reset: POST /v1/reset_conversation, POST /reset_conversation.
  • Health: GET /health — process_up, agent_loaded for liveness/readiness.
  • Tenant context: X-User-ID, X-Space-ID headers aligned with Python.

A2A (in-process)

  • Agent Card: GET /.well-known/agent-card.json (and compatible paths under /a2a).
  • JSON-RPC: POST /a2a/ — SendMessage, SendStreamingMessage.
  • TaskStore: in-memory or Redis; remote-agent discovery and delegation via enhanced orchestrator.
  • Details: A2A Guide (Chinese).

Adapters

Adapters bind the orchestrator to execution backends and wire middleware and external services into the runtime:

Layer Module Role
Shared adapters-common Engine-agnostic middleware clients (Redis, etc.), credential helpers, external-call DFX (timeout, retry, circuit breaker)
Agent Core leaf adapters-agentcore JiuwenCoreAgentHandler; registers Checkpointer/middleware into Core RunnerConfig; binds MCP, remote/A2A, Sandbox outbound SPI
Handler Configuration Backend
agentcore (default) openjiuwen.service.agent-id JiuwenCoreAgentHandler → Core Runner
custom @Bean AgentHandler override default binding (proxy, remote engine, etc.)

Details: Adapters & Handler (Chinese).

Lifecycle

  • Init / Shutdown hooks, readiness gate (agent_loaded), active stream tracking, in-process interrupt (no separate interrupt REST).

Scope & roadmap

Topic Path in repo Notes
Agent Server (HTTP + A2A) ✅ service/* main delivery today
Agent Runtime Manager ⏳ manager/* control plane, this repo
Platform A2A gateway ⏳ applications/* etc. or external platform service
App control plane ❌ /chat, Session CRUD not in Server scope

Project Structure

agent-runtime-java/                 # Agent Distributed Runtime (Java)
├── service/                        # Agent Server
│   ├── agent-service-spec/
│   ├── agent-service-adapters/
│   ├── agent-service-app/
│   └── agent-service-demo/
├── manager/（planned）             # Agent Runtime Manager
├── applications/（planned）
├── documents/zh/
│   └── SUMMARY.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── README.zh.md

Documentation

Index: documents/zh/SUMMARY.md (Chinese).

By goal:

Goal Start here
Run demo locally Quick Start · demo README
HTTP API & SSE HTTP Data Plane
A2A Server / Client A2A Guide · A2A vs platform
Custom Handler Adapters & Handler
Lifecycle & probes Lifecycle & Probes
Big picture Development Guide · Logical Architecture
Module layout service/README.md

Agent Core (agents, workflows, Runner): agent-core-java ([dependency pinning](documents/zh/2.开发指南/Agent Core 依赖.md)).

English documentation is planned; README is bilingual; detailed guides are currently Chinese-only.

Contributing

We welcome issues, documentation improvements, code, and usage feedback. See CONTRIBUTING.md.

License

This project is licensed under the Apache License 2.0.