Skip to content

Commit ee72a72

Browse files
authored
refactor: decouple ARGI runtime from model SDKs (agentic-ai-java#152)
* refactor: decouple ARGI runtime from model SDKs Introduce JDK-only argi-api contracts and four optional ChatClient adapters with Spring Boot auto-configuration. Migrate Graph, ReAct, built-in nodes and Studio to neutral model and tool contracts without legacy builder aliases. Group adapters and starters, verify independent API consumers and enforce SDK isolation across production sources, bytecode and runtime dependency trees. Add gated real-model integration tests and release dependency auditing. * feat Signed-off-by: yuluo-yx <[email protected]> * updated Signed-off-by: yuluo-yx <[email protected]> --------- Signed-off-by: yuluo-yx <[email protected]>
1 parent 6e732d0 commit ee72a72

541 files changed

Lines changed: 37595 additions & 28183 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/build-and-test.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ jobs:
5353
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
5454
- uses: ./tools/github-actions/setup-deps
5555
- run: make tools
56-
- run: make test
56+
- run: ./mvnw -B install
57+
- run: tools/scripts/verify-api-contract.sh --skip-install
5758
build:
5859
if: (github.repository == 'agentic-ai-java/argi')
5960
runs-on: ubuntu-22.04
@@ -90,7 +91,9 @@ jobs:
9091
path: |
9192
.flattened-pom.xml
9293
argi-*/.flattened-pom.xml
93-
spring-boot-starters/*/.flattened-pom.xml
94+
argi-api/*/.flattened-pom.xml
95+
argi-spring-boot-starter/*/.flattened-pom.xml
9496
argi-*/target/*.jar
95-
spring-boot-starters/*/target/*.jar
97+
argi-api/*/target/*.jar
98+
argi-spring-boot-starter/*/target/*.jar
9699
include-hidden-files: true

‎.github/workflows/release.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,12 +120,15 @@ jobs:
120120
path: |
121121
.flattened-pom.xml
122122
argi-*/.flattened-pom.xml
123-
spring-boot-starters/*/.flattened-pom.xml
123+
argi-api/*/.flattened-pom.xml
124+
argi-spring-boot-starter/*/.flattened-pom.xml
124125
target/*.asc
125126
argi-*/target/*.asc
126-
spring-boot-starters/*/target/*.asc
127+
argi-api/*/target/*.asc
128+
argi-spring-boot-starter/*/target/*.asc
127129
argi-*/target/*.jar
128-
spring-boot-starters/*/target/*.jar
130+
argi-api/*/target/*.jar
131+
argi-spring-boot-starter/*/target/*.jar
129132
target/central-publishing/*.zip
130133
target/central-publishing/*.json
131134
argi-bom/target/central-publishing/*.zip

‎AGENTS.md‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance for AI assistants working with the ARGI codebase.
44

55
## Project Overview
66

7-
ARGI (Agent Runtime and Graph Intelligence, pronounced "AR-jee") is a production-ready framework for building agents, workflows, and multi-agent applications. It is forked from Spring AI Alibaba and focuses on stateful agent runtime capabilities: graph orchestration, persistence, context engineering, and human-in-the-loop support. It also supports the multi-model integration capabilities provided by Spring AI.
7+
ARGI (Agent Runtime and Graph Intelligence, pronounced "AR-jee") is a production-ready framework for building agents, workflows, and multi-agent applications. It is forked from Spring AI Alibaba and focuses on stateful agent runtime capabilities: graph orchestration, persistence, context engineering, and human-in-the-loop support. Its runtime consumes framework-neutral `argi-api` contracts. Spring AI, LangChain4j, Google ADK Java, and AgentScope Java are isolated in optional adapters.
88

99
> **Naming:** the product display name is *ARGI*. Published Maven coordinates use `io.github.agentic-ai-java:argi-*`, Java packages use `io.github.agentic.ai`, configuration prefixes use `argi.*`, and framework-specific public class names use the `Argi*` prefix.
1010
@@ -14,23 +14,39 @@ ARGI (Agent Runtime and Graph Intelligence, pronounced "AR-jee") is a production
1414
- Context Engineering with human-in-the-loop, context compaction, editing, model call limits
1515
- Graph-based workflow with conditional routing, nested graphs, parallel execution
1616
- A2A (Agent-to-Agent) client support (Nacos service discovery lives in the Extensions repository)
17-
- Multi-model integration through Spring AI, plus MCP (Model Context Protocol)
17+
- Multi-model integration through four optional ChatClient adapters, plus MCP (Model Context Protocol)
1818
- Embedded visual debugging studio
1919

2020
## Repository Structure
2121

2222
```
2323
argi/
24+
├── argi-api/ # ChatClient contracts and framework adapters (directory group)
25+
│ ├── argi-api-base/ # Publishes argi-api; JDK-only public contracts
26+
│ ├── argi-adapter-spring-ai/
27+
│ ├── argi-adapter-langchain4j/
28+
│ ├── argi-adapter-google-adk/
29+
│ └── argi-adapter-agentscope/
2430
├── argi-agent-framework/ # Multi-agent framework (Sequential, Parallel, Routing, etc.)
2531
├── argi-graph-core/ # Runtime providing persistence, workflow orchestration, state mgmt
2632
├── argi-studio/ # Embedded UI for debugging agents visually
2733
├── argi-bom/ # Bill of Materials for dependency management
28-
├── spring-boot-starters/ # Spring Boot Starters
34+
├── argi-spring-boot-starter/ # Spring Boot Starters (directory group)
2935
│ ├── argi-starter-builtin-nodes/ # Built-in workflow nodes
30-
│ └── argi-starter-graph-observation/ # Observability
36+
│ ├── argi-starter-graph-observation/ # Observability
37+
│ ├── argi-starter-adapter-spring-ai/
38+
│ ├── argi-starter-adapter-langchain4j/
39+
│ ├── argi-starter-adapter-google-adk/
40+
│ └── argi-starter-adapter-agentscope/
3141
└── tools/ # Build and linting tools
3242
```
3343

44+
The directory groups are not additional Maven artifacts. The root `pom.xml` lists
45+
their child modules directly; every child inherits the root parent using
46+
`../../pom.xml`. The public API artifact remains `argi-api`, and its Java packages
47+
remain `io.github.agentic.ai.api.*`. Use artifact selectors such as `-pl :argi-api`
48+
or the complete child directory path when selecting a module for a build.
49+
3450
This repository holds the core only. Optional integrations live in separate repositories:
3551

3652
- [Extensions](https://github.com/agentic-ai-java/argi-extensions) - model and document contracts, A2A Nacos, config Nacos, AgentScope, JDBC/Redis/MongoDB graph persistence, the Docker code executor, and the tool-call sandbox.
@@ -77,9 +93,11 @@ make licenses-check
7793

7894
### Technology Stack
7995

80-
- **Framework**: Spring Boot 4.1.x, Spring AI 2.0.x
81-
- **Model and Integration Layer**: Spring AI multi-model integrations, model starters, MCP, A2A, and Nacos
82-
- **Observability**: Spring Cloud Observation (Micrometer/OpenTelemetry)
96+
- **Framework**: Java 17; Spring Boot 4.1.x for optional starters and Studio
97+
- **Model and Integration Layer**: `argi-api` contracts and four isolated provider adapters; MCP and A2A integrations
98+
- **Observability**: Lightweight Micrometer observation; no required OpenTelemetry deployment
99+
100+
Core production sources, bytecode, and runtime dependency trees must remain free of provider SDKs. Native SDKs in core test fixtures must use test scope. This is a breaking replacement, not a deprecated compatibility bridge.
83101

84102
## Code Style & Conventions
85103

@@ -139,10 +157,10 @@ The project uses `make` for linting tasks:
139157
## Tips for AI Assistants
140158

141159
1. **JDK Version**: Project targets JDK 17. Use appropriate language features.
142-
2. **Spring Boot**: Uses Spring Boot 4.1.1 with Spring AI 2.0.1. The `jakarta.*` namespace applies throughout; there is no `javax.*` code.
160+
2. **Spring Boot**: Uses Spring Boot 4.1.1. Spring AI 2.0.1 belongs only to its adapter and native test fixtures. The `jakarta.*` namespace applies throughout; there is no `javax.*` code.
143161
3. **Dependencies**: Check `argi-bom` or parent pom for version management.
144162
4. **Makefile**: Use the Makefile in the root for project maintenance tasks (linting, license checks).
145-
5. **Structure**: When adding new features, prefer creating or updating modules within `argi-agent-framework` or `spring-boot-starters` depending on the scope.
163+
5. **Structure**: Keep neutral contracts and framework adapters in `argi-api`, Spring Boot auto-configuration in `argi-spring-boot-starter`, and agent runtime features in `argi-agent-framework`.
146164

147165
## Important Links
148166

‎CONTRIBUTING-zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## 感谢你为 ARGI 贡献!
44

5-
ARGI 从开源建设以来,受到了很多社区同学的关注。社区的每一个 Issue ,每一个 PR,都是对整个项目的帮助,都在为建设更好用的 Spring AI 添砖加瓦。
5+
ARGI 从开源建设以来,受到了很多社区同学的关注。社区的每一个 Issue ,每一个 PR,都是对整个项目的帮助,都在为建设更好用的 ARGI 添砖加瓦。
66

77
我们真心地感谢为这个项目提出过 Issue 和 PR 的开发者。我们希望有更多社区的开发者加入进来,一起把项目做好。
88

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## Thank you for contributing to ARGI!
66

7-
Since its open-source inception, ARGI has received attention from many community members. Every Issue and PR from the community helps the entire project and contributes to building a better Spring AI.
7+
Since its open-source inception, ARGI has received attention from many community members. Every Issue and PR from the community helps the entire project and contributes to building a better ARGI.
88

99
We sincerely thank the developers who have submitted Issues and PRs for this project. We hope more community developers will join us to make this project even better.
1010

@@ -67,9 +67,19 @@ To ensure code cleanliness, please remove any unused imports in your Java files.
6767

6868
Use the `type(scope): description` format for commit messages and PR titles; `scope` is optional. Common types are `fix`, `feat`, `refactor`, `docs`, `chore`, `perf`, `infra`, `revert`, `release`, `test`, and `style`.
6969

70-
GitHub Actions checks do not run when a pull request is opened or updated, and no welcome message or label is added automatically. Once a pull request is reviewed and merged into `main`, CI runs the build, test, lint, license, and secret checks on the `push` event; pushing directly to `main` triggers the same checks. Review requirements are managed by repository branch protection or rulesets.
71-
72-
Because nothing runs at pull-request time, run the local checks yourself before submitting.
70+
The build-and-test workflow runs on pull requests targeting `main` and pushes to
71+
`main`; feature-branch pushes do not trigger a second full pipeline. Job repository
72+
guards restrict runs to `agentic-ai-java/argi`, but do **not** exclude fork-origin
73+
pull requests opened against that upstream repository. Those runs execute the PR
74+
checkout's local actions and scripts with read-only repository permissions and
75+
without repository secrets. GitHub's fork-workflow approval settings still apply;
76+
maintainers should review untrusted workflow/script changes before approving runs.
77+
No welcome message or label is added automatically. Review requirements are
78+
managed by repository branch protection or rulesets.
79+
80+
Run local checks before submitting even when upstream CI is available. The CI
81+
test job installs the tested artifacts once, then uses
82+
`verify-api-contract.sh --skip-install` to compile the independent consumer.
7383

7484
Commit format example:
7585

‎README-zh.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ ARGI 是 **Agent Runtime and Graph Intelligence** 的缩写,读作 **“AR-jee
2828
- **上下文工程**:支持上下文压缩与编辑、调用限制、工具重试、规划和动态工具选择。
2929
- **图工作流**:支持条件路由、并行执行、嵌套图、状态持久化和中断恢复。
3030
- **智能体运行时基础**:提供模型无关的智能体编排、工作流状态和可嵌入调试支持。
31-
- **开放集成**:支持使用 Spring AI 提供的多模型集成能力,并提供工具调用、MCP、A2A 和 Nacos。
31+
- **开放集成**:通过中立 ChatClient 接入 Spring AI、LangChain4j、Google ADK 和 AgentScope,并提供工具调用、MCP、A2A 和 Nacos。
3232
- **可视化调试**:提供可嵌入 Spring Boot 应用的 Agent Chat UI。
3333

3434
## 快速开始
@@ -49,19 +49,20 @@ cd argi-examples
4949
mvn -f examples/chatbot/pom.xml spring-boot:run
5050
```
5151

52-
示例还需要对应版本的 Extensions BOM 和模型 Starter,依赖准备方式见[示例说明](https://github.com/agentic-ai-java/argi-examples/tree/main/examples#环境与依赖)。
52+
示例还需要对应版本的 Extensions BOM 和模型 Starter,依赖准备方式见[示例说明](https://github.com/agentic-ai-java/argi-examples/tree/main/examples#环境与依赖)。仍使用旧 Spring AI Agent Builder 的示例需要按 [API 与 Adapter](argi-api/README.md) 中的直接替换说明迁移;本次修改不包含外部示例仓库的迁移。
5353

5454
启动后访问 [http://localhost:8080/chatui/index.html](http://localhost:8080/chatui/index.html)。其他模型的配置方式请参阅[快速开始](https://agentic-ai-java.github.io/argi-website/docs/quick-start)。
5555

5656
## 项目模块
5757

5858
| 模块 | 说明 |
5959
| --- | --- |
60+
| [API 与 Adapter](argi-api) | 中立 ChatClient 契约及 Spring AI、LangChain4j、Google ADK、AgentScope 接入 |
6061
| [Agent Framework](argi-agent-framework) | 智能体开发与多智能体编排 |
6162
| [Graph Core](argi-graph-core) | 状态管理、持久化和工作流运行时 |
6263
| [Studio](argi-studio) | Agent 可视化调试界面 |
6364
| [Sandbox](https://github.com/agentic-ai-java/argi-extensions/tree/main/sandbox/argi-sandbox) | 工具调用的可选隔离执行环境,由 Extensions 维护 |
64-
| [Spring Boot Starters](spring-boot-starters) | 内置图节点和图可观测性 |
65+
| [Spring Boot Starters](argi-spring-boot-starter) | 内置图节点、图可观测性与四个 Adapter 的自动配置 |
6566
| [Extensions](https://github.com/agentic-ai-java/argi-extensions) | 模型与文档契约、A2A、Nacos、AgentScope、存储等可选扩展 |
6667
| [Examples](https://github.com/agentic-ai-java/argi-examples/tree/main/examples) | Chatbot、多智能体、图工程和文档示例 |
6768
| [Benchmark](benchmark) | [ARGI 基准测试项目](https://github.com/agentic-ai-java/argi-benchmark) |

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ ARGI stands for **Agent Runtime and Graph Intelligence** and is pronounced **"AR
2828
- **Context engineering**: context compaction and editing, call limits, tool retries, planning, and dynamic tool selection.
2929
- **Graph workflows**: conditional routing, parallel execution, nested graphs, state persistence, and interruption recovery.
3030
- **Agent runtime foundation**: provider-neutral agent orchestration, workflow state, and embeddable debugging support.
31-
- **Open integrations**: support for multi-model integration capabilities provided by Spring AI, plus tool calling, MCP, A2A, and Nacos.
31+
- **Open integrations**: a neutral ChatClient with Spring AI, LangChain4j, Google ADK, and AgentScope adapters, plus tool calling, MCP, A2A, and Nacos.
3232
- **Visual debugging**: an embeddable Agent Chat UI for Spring Boot applications.
3333

3434
## Quick Start
@@ -49,19 +49,20 @@ cd argi-examples
4949
mvn -f examples/chatbot/pom.xml spring-boot:run
5050
```
5151

52-
The examples also require the matching Extensions BOM and provider starters. See the [example setup](https://github.com/agentic-ai-java/argi-examples/tree/main/examples#环境与依赖).
52+
The examples also require the matching Extensions BOM and provider starters. See the [example setup](https://github.com/agentic-ai-java/argi-examples/tree/main/examples#环境与依赖). Examples using older Spring AI agent builders require the direct-replacement migration described in [API and Adapters](argi-api/README.md); that external repository is not migrated by this change.
5353

5454
Open [http://localhost:8080/chatui/index.html](http://localhost:8080/chatui/index.html). See the [Quick Start](https://agentic-ai-java.github.io/argi-website/en/docs/quick-start) for other model providers.
5555

5656
## Modules
5757

5858
| Module | Description |
5959
| --- | --- |
60+
| [API and Adapters](argi-api) | Framework-neutral ChatClient contracts and Spring AI, LangChain4j, Google ADK, and AgentScope adapters |
6061
| [Agent Framework](argi-agent-framework) | Agent development and multi-agent orchestration |
6162
| [Graph Core](argi-graph-core) | State management, persistence, and workflow runtime |
6263
| [Studio](argi-studio) | Visual debugging UI for agents |
6364
| [Sandbox](https://github.com/agentic-ai-java/argi-extensions/tree/main/sandbox/argi-sandbox) | Optional isolated execution environment for tool calls, maintained in Extensions |
64-
| [Spring Boot Starters](spring-boot-starters) | Built-in graph nodes and graph observability |
65+
| [Spring Boot Starters](argi-spring-boot-starter) | Built-in graph nodes, graph observability, and four adapter auto-configurations |
6566
| [Extensions](https://github.com/agentic-ai-java/argi-extensions) | Model and document contracts, A2A, Nacos, AgentScope, storage, and other optional integrations |
6667
| [Examples](https://github.com/agentic-ai-java/argi-examples/tree/main/examples) | Chatbot, multi-agent, graph engineering, and documentation examples |
6768
| [Benchmark](benchmark) | [argi-benchmark](https://github.com/agentic-ai-java/argi-benchmark) |

‎argi-agent-framework/pom.xml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,61 @@
3838
</scm>
3939

4040
<dependencies>
41+
<dependency>
42+
<groupId>org.jspecify</groupId>
43+
<artifactId>jspecify</artifactId>
44+
</dependency>
45+
<dependency>
46+
<groupId>io.github.agentic-ai-java</groupId>
47+
<artifactId>argi-api</artifactId>
48+
<version>${project.parent.version}</version>
49+
</dependency>
50+
<dependency>
51+
<groupId>io.github.agentic-ai-java</groupId>
52+
<artifactId>argi-adapter-spring-ai</artifactId>
53+
<version>${project.parent.version}</version>
54+
<scope>test</scope>
55+
</dependency>
56+
<dependency>
57+
<groupId>io.github.agentic-ai-java</groupId>
58+
<artifactId>argi-adapter-langchain4j</artifactId>
59+
<version>${project.parent.version}</version>
60+
<scope>test</scope>
61+
</dependency>
62+
<dependency>
63+
<groupId>io.github.agentic-ai-java</groupId>
64+
<artifactId>argi-adapter-google-adk</artifactId>
65+
<version>${project.parent.version}</version>
66+
<scope>test</scope>
67+
</dependency>
68+
<dependency>
69+
<groupId>io.github.agentic-ai-java</groupId>
70+
<artifactId>argi-adapter-agentscope</artifactId>
71+
<version>${project.parent.version}</version>
72+
<scope>test</scope>
73+
</dependency>
4174
<dependency>
4275
<groupId>io.github.agentic-ai-java</groupId>
4376
<artifactId>argi-graph-core</artifactId>
4477
<version>${project.parent.version}</version>
4578
</dependency>
4679

80+
<dependency>
81+
<groupId>com.github.victools</groupId>
82+
<artifactId>jsonschema-generator</artifactId>
83+
<version>5.0.0</version>
84+
</dependency>
85+
<dependency>
86+
<groupId>com.github.victools</groupId>
87+
<artifactId>jsonschema-module-jackson</artifactId>
88+
<version>5.0.0</version>
89+
</dependency>
90+
<dependency>
91+
<groupId>org.antlr</groupId>
92+
<artifactId>ST4</artifactId>
93+
<version>4.3.4</version>
94+
</dependency>
95+
4796
<dependency>
4897
<groupId>io.github.a2asdk</groupId>
4998
<artifactId>a2a-java-sdk-client</artifactId>
@@ -71,6 +120,11 @@
71120
<artifactId>snakeyaml</artifactId>
72121
</dependency>
73122

123+
<dependency>
124+
<groupId>com.networknt</groupId>
125+
<artifactId>json-schema-validator</artifactId>
126+
</dependency>
127+
74128
<dependency>
75129
<groupId>com.github.ben-manes.caffeine</groupId>
76130
<artifactId>caffeine</artifactId>
@@ -88,12 +142,32 @@
88142
<scope>test</scope>
89143
</dependency>
90144

145+
<dependency>
146+
<groupId>io.projectreactor</groupId>
147+
<artifactId>reactor-test</artifactId>
148+
<scope>test</scope>
149+
</dependency>
150+
91151
<dependency>
92152
<groupId>org.springframework.ai</groupId>
93153
<artifactId>spring-ai-starter-model-openai</artifactId>
94154
<scope>test</scope>
95155
</dependency>
96156

157+
<dependency>
158+
<groupId>dev.langchain4j</groupId>
159+
<artifactId>langchain4j-open-ai</artifactId>
160+
<version>${langchain4j.version}</version>
161+
<scope>test</scope>
162+
</dependency>
163+
164+
<dependency>
165+
<groupId>io.agentscope</groupId>
166+
<artifactId>agentscope-extensions-model-openai</artifactId>
167+
<version>${agentscope.version}</version>
168+
<scope>test</scope>
169+
</dependency>
170+
97171
<dependency>
98172
<groupId>org.springframework.ai</groupId>
99173
<artifactId>spring-ai-starter-model-deepseek</artifactId>

0 commit comments

Comments
 (0)