Ai4j

ai4j

一款面向 JDK8+ 的 Java AI Agentic 开发套件，既提供统一的大模型调用与常用 AI 基座能力，也提供更完善的智能体式 Agent 开发能力。 覆盖多平台模型接入、统一输入输出、Tool Call、MCP、RAG、统一 VectorStore、ChatMemory、Agent Runtime、Coding Agent、CLI / TUI / ACP、FlowGram 集成，以及 Dify / Coze / n8n 等已发布 AgentFlow 端点接入能力，帮助 Java 应用从基础模型接入扩展到更完整的 agentic 应用开发。

当前仓库已经演进为多模块 SDK，除核心 ai4j 外，还提供 ai4j-extension-api、ai4j-plugin-ask-user、ai4j-agent、ai4j-coding、ai4j-cli、ai4j-spring-boot-starter、ai4j-flowgram-spring-boot-starter、ai4j-bom。如果只需要基础大模型调用，优先引入 ai4j；如果需要插件包、Agent、Coding Agent、CLI / ACP、Spring Boot 或 FlowGram 集成，再按模块引入对应能力。

赞助商

• TroveBox AI 中转平台：提供 AI API 中转服务，低至 0.1x 倍率。

适用场景与常见方案对比

| 方案 | Java 基线 | 应用形态 | 能力侧重点 | | --- | --- | --- | --- | | ai4j | JDK8+ | 普通 Java / Spring | 统一大模型接入、Tool / MCP / RAG、Agent Runtime、Coding Agent、CLI / TUI / ACP | | Spring AI | Java 17+ | Spring Boot 3.x | Spring 原生 AI 集成、模型访问、Tool Calling、MCP、RAG | | Spring AI Alibaba | Java 17+ | Spring Boot 3.x | Spring 与阿里云 AI 生态整合 | | LangChain4j | Java 17+ | 普通 Java / Spring / Quarkus 等 | 通用 Java LLM / Agent / RAG 抽象、AI Services、多框架集成 |

支持的平台

• OpenAi(包含与OpenAi请求格式相同/兼容的平台)
• Jina（Rerank / Jina-compatible Rerank）
• Zhipu(智谱)
• DeepSeek(深度求索)
• Moonshot(月之暗面)
• Hunyuan(腾讯混元)
• Lingyi(零一万物)
• Ollama
• MiniMax
• Baichuan

支持的服务

• Chat Completions（流式与非流式）
• Responses
• Embedding
• Rerank
• Audio
• Image
• Realtime

已适配的 AgentFlow / 工作流平台

• Dify（Chat / Workflow）
• Coze（Chat / Workflow）
• n8n（Webhook Workflow）

特性

• 支持MCP服务，内置MCP网关，支持建立动态MCP数据源。
• 支持Spring以及普通Java应用、支持Java 8以上的应用
• 多平台、多服务
• 提供 AgentFlow 能力，可直接接入 Dify、Coze、n8n 等已发布 Agent / Workflow 端点
• 提供 ai4j-agent 通用 Agent 运行时，支持 ReAct、subagent、agent teams、memory、trace 与 tool loop
• 内置 Coding Agent CLI / TUI，支持本地代码仓交互式会话、provider profile、workspace model override、session/process 管理
• 提供 ai4j-coding Coding Agent 运行时，支持 workspace tools、outer loop、checkpoint compaction、subagent 与 team 协作
• 提供 ai4j-flowgram-spring-boot-starter，便于在 Spring Boot 中接入 FlowGram 工作流与 trace
• 提供 ai4j-extension-api 与官方 ai4j-plugin-ask-user 样板插件，用于按需扩展 Agent / Coding Agent 工具、命令、Skill 与 Prompt
• 提供 ai4j-bom，便于多模块项目统一版本管理
• 统一的输入输出
• 统一的错误处理
• 支持SPI机制，可自定义Dispatcher和ConnectPool
• 支持服务增强，例如增加websearch服务
• 支持流式输出。支持函数调用参数流式输出.
• 简洁的多模态调用方式，例如vision识图
• 轻松使用Tool Calls
• 支持多个函数同时调用（智谱不支持）
• 支持stream_options，流式输出直接获取统计token usage
• 内置 ChatMemory，支持基础多轮会话上下文维护，可同时适配 Chat / Responses
• 支持RAG，内置统一 VectorStore 抽象，当前支持: Pinecone、Qdrant、pgvector、Milvus
• 内置 IngestionPipeline，统一串联 DocumentLoader -> Chunker -> MetadataEnricher -> Embedding -> VectorStore.upsert
• 内置 DenseRetriever、Bm25Retriever、HybridRetriever，可按语义检索、关键词检索、混合检索方式组合知识库召回
• HybridRetriever 支持 RrfFusionStrategy、RsfFusionStrategy、DbsfFusionStrategy，默认使用 RRF；融合排序与 Reranker 语义精排解耦
• 支持统一 IRerankService，当前可接 Jina / Jina-compatible、Ollama、Doubao(方舟知识库重排)；可通过 ModelReranker 无缝接入 RAG 精排
• RAG 运行时可直接拿到 rank/retrieverSource/retrievalScore/fusionScore/rerankScore/scoreDetails/trace，并可通过 RagEvaluator 计算 Precision@K/Recall@K/F1@K/MRR/NDCG
• 使用Tika读取文件
• Token统计TikTokensUtil.java

官方文档站

• 在线文档站：https://lnyo-cly.github.io/ai4j/
• 文档站源码位于 docs-site/
• 5 分钟跑通第一条请求：docs-site/docs/start-here/five-minute-first-chat.md
• 普通 Java 接入：docs-site/docs/start-here/quickstart-java.md
• Spring Boot 接入：docs-site/docs/start-here/quickstart-spring-boot.md
• 能力边界与路径选择：docs-site/docs/start-here/feature-map.md
• 插件包生态与第三方扩展：docs-site/docs/core-sdk/extension/plugin-packages.md
• 官方 Ask User 插件：docs-site/docs/core-sdk/extension/ask-user-plugin.md
• Spring Boot 插件配置：ai.extensions.enabled + ai.extensions.tools.expose
• CLI 插件骨架生成：ai4j-cli extension init --id --package
• CLI 插件校验：ai4j-cli extension validate |--all
• CLI 插件接入门禁：ai4j-cli extension check --enable [activation options]
• CLI 插件命令执行：ai4j-cli extension run --enable [arguments...]
• CLI 插件资源读取：ai4j-cli extension resource --enable
• 插件 Guardrail：已启用插件可在 Agent / Coding Agent 执行 tool call 前拦截内置工具与扩展工具
• 协议、Agent 与上层集成：docs-site/docs/mcp/、docs-site/docs/agent/、docs-site/docs/coding-agent/、docs-site/docs/flowgram/

推荐阅读顺序：

• docs-site/docs/intro.md
• docs-site/docs/start-here/five-minute-first-chat.md
• docs-site/docs/start-here/quickstart-java.md 或 docs-site/docs/start-here/quickstart-spring-boot.md
• docs-site/docs/start-here/first-chat.md
• docs-site/docs/core-sdk/overview.md
• docs-site/docs/core-sdk/extension/plugin-packages.md
• docs-site/docs/mcp/overview.md

如果使用支持 Skills 的 agent 工具，可以安装用户侧接入 Skill：

npx skills add LnYo-Cly/ai4j --skill ai4j-app-builder

基础会话上下文新增入口：

• docs-site/docs/ai-basics/chat/chat-memory.md
• docs-site/docs/ai-basics/services/rerank.md
• docs-site/docs/ai-basics/rag/ingestion-pipeline.md

本地运行文档站：

cd .\docs-site
npm install
npm run start

cd .\docs-site
npm run build

更新日志

• [2026-03-28] 修复 Coding Agent ACP 流式场景下纯空白 chunk 被 runtime 过滤的问题；ACP 保持透传原始 delta，不做 chunk 聚合；补充 CLI/文档中的流式语义说明
• [2026-03-26] 新增 Coding Agent CLI / TUI 文档与能力说明，覆盖交互式会话、provider profile、workspace model override、命令参考与配置样例
• [2025-08-19] 修复传递有验证参数的sse-url时，key丢失问题
• [2025-08-08] OpenAi: maxtokens字段现已废弃，推荐使用maxcompletiontokens(GPT-5已经不支持maxtokens字段)
• [2025-08-08] 支持MCP协议，支持STDIO,SSE,Streamable HTTP; 支持MCP Server与MCP Client; 支持MCP网关; 支持自定义MCP数据源; 支持MCP自动重连
• [2025-06-23] 修复ollama的流式错误；修复ollama函数调用的错误；修复moonshot请求时错误；修复ollama embedding错误；修复思考无内容；修复日志冲突；新增自定义异常方法。
• [2025-02-28] 新增对Ollama平台的embedding接口的支持。
• [2025-02-17] 新增对DeepSeek平台推理模型的适配。
• [2025-02-12] 为Ollama平台添加Authorization
• [2025-02-11] 实现自定义的Jackson序列化，解决OpenAi已经无法通过Json String来直接实现多模态接口的问题。
• [2024-12-12] 使用装饰器模式增强Chat服务，支持SearXNG网络搜索增强，无需模型支持内置搜索以及function_call。
• [2024-10-17] 支持SPI机制，可自定义Dispatcher和ConnectPool。新增百川Baichuan平台Chat接口支持。
• [2024-10-16] 增加MiniMax平台Chat接口对接
• [2024-10-15] 增加realtime服务
• [2024-10-12] 修复早期遗忘的小bug; 修复错误拦截器导致的音频字节流异常错误问题; 增加OpenAi Audio服务。
• [2024-10-10] 增强对SSE输出的获取，新加入currData属性，记录当前消息的整个对象。而原先的currStr为当前消息的content内容，保留不变。
• [2024-09-26] 修复有关Pinecone向量数据库的一些问题。发布0.6.3版本
• [2024-09-20] 增加对Ollama平台的支持，并修复一些bug。发布0.6.2版本
• [2024-09-19] 增加错误处理链，统一处理为openai错误类型; 修复部分情况下URL拼接问题，修复拦截器中response重复调用而导致的关闭问题。发布0.5.3版本
• [2024-09-12] 修复上个问题OpenAi参数导致错误的遗漏，发布0.5.2版本
• [2024-09-12] 修复SpringBoot 2.6以下导致OkHttp变为3.14版本的报错问题；修复OpenAi参数parallel_tool_calls在tools为null时的异常问题。发布0.5.1版本。
• [2024-09-09] 新增零一万物大模型支持、发布0.5.0版本。
• [2024-09-02] 新增腾讯混元Hunyuan平台支持（注意：所需apiKey 属于SecretId与SecretKey的拼接，格式为 {SecretId}.{SecretKey}），发布0.4.0版本。
• [2024-08-30] 新增对Moonshot(Kimi)平台的支持，增加OkHttpUtil.java实现忽略SSL证书的校验。
• [2024-08-29] 新增对DeepSeek平台的支持、新增stream_options可以直接统计usage、新增错误拦截器ErrorInterceptor.java、发布0.3.0版本。
• [2024-08-29] 修改SseListener以兼容智谱函数调用。
• [2024-08-28] 添加token统计、添加智谱AI的Chat服务、优化函数调用可以支持多轮多函数。
• [2024-08-17] 增强SseListener监听器功能。发布0.2.0版本。

教程文档

• 快速接入SpringBoot、接入流式与非流式以及函数调用
• Java快速接入qwen2.5、llama3.1等Ollama平台开源大模型
• Java搭建法律AI助手，快速实现RAG应用
• 大模型不支持联网搜索？为Deepseek、Qwen、llama等本地模型添加网络搜索
• java快速接入mcp以及结合mysql动态管理

Coding Agent CLI / TUI

AI4J 目前已经内置 ai4j-cli，可以直接作为本地 coding agent 使用，支持：

• one-shot 与持续会话
• CLI / TUI 两种交互模式
• provider profile 持久化
• workspace 级 model override
• subagent 与 agent teams 协作
• session 持久化、resume、fork、history、tree、events、replay
• team board、team messages、team resume 等协作观测能力
• process 管理与日志查看

安装

curl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh

irm https://lnyo-cly.github.io/ai4j/install.ps1 | iex

安装脚本会从 Maven Central 下载 ai4j-cli 并生成 ai4j 命令，前提是本机已经安装 Java 8+。

one-shot 示例

ai4j code `
  --provider openai `
  --protocol responses `
  --model gpt-5-mini `
  --prompt "Read README and summarize the project structure"

交互式 CLI 示例

ai4j code `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .

TUI 示例

ai4j tui `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .

ACP 示例

ai4j acp `
  --provider openai `
  --protocol responses `
  --model gpt-5-mini `
  --workspace .

源码构建（可选）

mvn -pl ai4j-cli -am -DskipTests package

产物示例：

ai4j-cli/target/ai4j-cli--jar-with-dependencies.jar

如果你需要直接运行本地构建产物：

java -jar .\ai4j-cli\target\ai4j-cli--jar-with-dependencies.jar code --help

当前协议规则

当前 CLI 对用户只暴露两种协议：

• chat
• responses

如果省略 --protocol，会按 provider/baseUrl 在本地推导默认值：

• openai + 官方 OpenAI host -> responses
• openai + 自定义兼容 baseUrl -> chat
• doubao / dashscope -> responses
• 其他 provider -> chat

注意：

• 不再对用户暴露 auto
• 旧配置中的 auto 会在读取时自动归一化为显式协议

provider profile 配置位置

• 全局配置：~/.ai4j/providers.json
• 工作区配置：/.ai4j/workspace.json

推荐工作流：

• 全局保存长期可复用 profile
• workspace 只引用当前 activeProfile
• 临时切模型时使用 workspace 的 modelOverride

workspace.json 也可以显式挂载额外 skill 目录：

{
  "activeProfile": "openai-main",
  "modelOverride": "gpt-5-mini",
  "enabledMcpServers": ["fetch"],
  "skillDirectories": [
    ".ai4j/skills",
    "C:/skills/team",
    "../shared-skills"
  ]
}

skill 发现规则：

• 默认扫描 /.ai4j/skills
• 默认扫描 ~/.ai4j/skills
• skillDirectories 中的相对路径按 workspace 根目录解析
• 进入 CLI 后可用 /skills 查看当前发现到的 skill
• 可用 /skills 查看某个 skill 的路径、来源、描述和扫描 roots，不打印 SKILL.md 正文

/stream、Esc 与状态提示

当前 /stream 的语义是“当前 CLI 会话里的模型请求是否启用 stream”，不是单纯的 transcript 渲染开关：

• 作用域是当前 CLI 会话
• /stream on|off 会切换请求级 stream=true|false，并立即重建当前 session runtime
• on 时 provider 响应按增量到达，assistant 文本也按增量呈现
• off 时等待完整响应后再输出整理后的完成块
• 流式 event 粒度由上游 provider/SSE 决定，不保证“一个 event = 一个 token”
• 如果通过 ACP/IDE 接入，宿主应按收到的 chunk 顺序渲染，并保留换行与空白

当前交互壳层里：

• Esc 在活跃 turn 中断当前任务；空闲时关闭 palette 或清空输入
• 状态栏会显示 Thinking、Connecting、Responding、Working、Retrying
• 一段时间没有新进展会升级为 Waiting
• 更久没有新进展会显示 Stalled，并提示 press Esc to interrupt

常用命令

• /providers
• /provider
• /provider use
• /provider save
• /provider add --provider [--protocol ] [--model ] [--base-url ] [--api-key ]
• /provider edit [--provider ] [--protocol ] [--model |--clear-model] [--base-url |--clear-base-url] [--api-key |--clear-api-key]
• /provider default
• /provider remove
• /model
• /model
• /model reset
• /skills
• /skills
• /stream [on|off]
• /processes
• /process status|follow|logs|write|stop ...
• /resume / /load / /fork ...

文档入口

• [Coding Agent 总览](docs-site/docs/coding-agent/overview.md)
• [Coding Agent 快速开始](docs-site/docs/coding-agent/quickstart.md)
• [CLI / TUI 使用指南](docs-site/docs/coding-agent/cli-and-tui.md)
• [会话、流式与进程](docs-site/docs/coding-agent/session-runtime.md)
• [配置体系](docs-site/docs/coding-agent/configuration.md)
• [Tools 与审批机制](docs-site/docs/coding-agent/tools-and-approvals.md)
• [Skills 使用与组织](docs-site/docs/coding-agent/skills.md)
• [MCP 对接](docs-site/docs/coding-agent/mcp-integration.md)
• [ACP 集成](docs-site/docs/coding-agent/acp-integration.md)
• [TUI 定制与主题](docs-site/docs/coding-agent/tui-customization.md)
• [命令参考](docs-site/docs/coding-agent/command-reference.md)

其它支持

• [[低价中转平台] 低价ApiKey—限时特惠 ](https://api.trovebox.online/)
• [[在线平台] 每日白嫖额度-所有模型均可使用 ](https://chat.trovebox.online/)

快速开始

导入

模块选型

• 只需要基础 LLM / Tool Call / MCP / RAG 能力：引入 ai4j
• 需要通用 Agent 运行时：引入 ai4j-agent
• 需要 Coding Agent、workspace tools、outer loop：引入 ai4j-coding
• 需要本地 CLI / TUI / ACP 宿主：引入 ai4j-cli
• 需要 Spring Boot 自动配置：引入 ai4j-spring-boot-starter
• 需要 FlowGram 工作流集成：引入 ai4j-flowgram-spring-boot-starter
• 需要开发第三方插件：引入 ai4j-extension-api
• 需要让 Agent 结构化询问用户：引入 ai4j-plugin-ask-user
• 同时引入多个模块：建议额外引入 ai4j-bom

Gradle

implementation platform("io.github.lnyo-cly:ai4j-bom:${project.version}")
implementation "io.github.lnyo-cly:ai4j"
implementation "io.github.lnyo-cly:ai4j-agent"
implementation "io.github.lnyo-cly:ai4j-plugin-ask-user"

implementation group: 'io.github.lnyo-cly', name: 'ai4j', version: '${project.version}'

implementation group: 'io.github.lnyo-cly', name: 'ai4j-spring-boot-starter', version: '${project.version}'

Maven

    
        
            io.github.lnyo-cly
            ai4j-bom
            ${project.version}
            pom
            import
        
    

    io.github.lnyo-cly
    ai4j-agent

    io.github.lnyo-cly
    ai4j-coding

    io.github.lnyo-cly
    ai4j-plugin-ask-user

    io.github.lnyo-cly
    ai4j
    ${project.version}

    io.github.lnyo-cly
    ai4j-spring-boot-starter
    ${project.version}

获取AI服务实例

非Spring首聊推荐

如果只是先跑通第一条同步 Chat 请求，直接使用 AI4J 的核心对象链：

import io.github.lnyocly.ai4j.config.OpenAiConfig;
import io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatCompletion;
import io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatCompletionResponse;
import io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatMessage;
import io.github.lnyocly.ai4j.service.Configuration;
import io.github.lnyocly.ai4j.service.IChatService;
import io.github.lnyocly.ai4j.service.PlatformType;
import io.github.lnyocly.ai4j.service.factory.AiService;

public class Ai4jFirstChat {
    public static void main(String[] args) throws Exception {
        OpenAiConfig openAiConfig = new OpenAiConfig();
        openAiConfig.setApiKey(System.getenv("OPENAI_API_KEY"));

        Configuration configuration = new Configuration();
        configuration.setOpenAiConfig(openAiConfig);

        AiService aiService = new AiService(configuration);
        IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

        ChatCompletion request = ChatCompletion.builder()
                .model("gpt-4o-mini")
                .message(ChatMessage.withUser("用一句话介绍 AI4J"))
                .build();

        ChatCompletionResponse response = chatService.chatCompletion(request);
        String text = response.getChoices().get(0).getMessage().getContent().getText();
        System.out.println(text);
    }
}

这条路径也是 AI4J 的真实主线：Configuration -> AiService -> IChatService -> ChatCompletion -> ChatCompletionResponse。后续自定义 OkHttpClient、代理、超时、流式、多模态、Tool、MCP、RAG 或读取完整 ChatCompletionResponse 时，都沿着同一条对象链继续扩展。

非Spring进阶获取

    public void test_init(){
        OpenAiConfig openAiConfig = new OpenAiConfig();

        Configuration configuration = new Configuration();
        configuration.setOpenAiConfig(openAiConfig);

        HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();
        httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);

        OkHttpClient okHttpClient = new OkHttpClient
                .Builder()
                .addInterceptor(httpLoggingInterceptor)
                .addInterceptor(new ErrorInterceptor())
                .connectTimeout(300, TimeUnit.SECONDS)
                .writeTimeout(300, TimeUnit.SECONDS)
                .readTimeout(300, TimeUnit.SECONDS)
                .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1",10809)))
                .build();
        configuration.setOkHttpClient(okHttpClient);

        AiService aiService = new AiService(configuration);

        embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);
        chat

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LnYo-Cly](https://github.com/LnYo-Cly)
- **Source:** [LnYo-Cly/ai4j](https://github.com/LnYo-Cly/ai4j)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.