AgentbaseDocs
文档目录

Server SDK(Java)

Java 后端 / 工具以项目 API Key 调用 Server SDK(io.agentbase:agentbase-java-sdk)。API Key 请求跳过行级权限检查(hasRole),只存受控服务端。Node / Python / Go 面见同目录 nodejs.md / python.md / go.md。

制品与安装

Java SDK 以 ZIP 交付包发布(不发布到 Maven registry),托管在 agentbase-sdks release v2.9.0;下载、双层 SHA256SUMS 校验与 mvn install:install-file 完整步骤见 ../integration.md(路径二)与 ../examples/java.md「获取与校验」。运行时:Java 11 source/target(OpenJDK 11/17 可跑);transport 为 OkHttp(解包目录 lib/ 携带运行时依赖,直接用 JAR 时必须连 lib/ 一起分发)。

初始化

import io.agentbase.Client;
import io.agentbase.services.TablesDB;
import io.agentbase.Query;
import io.agentbase.ID;

Client client = new Client()
    .setEndpoint(System.getenv("APPBASE_ENDPOINT"))   // https://appbuild.oceanbase.com/v1
    .setProject(System.getenv("APPBASE_PROJECT_ID"))
    .setKey(System.getenv("APPBASE_API_KEY"));        // 最小 scope 的项目 API Key

TablesDB tables = new TablesDB(client);               // 服务逐个构造

调用风格:方法为同步位置参数,默认返回类型化 model 或 Map<String,Object>;自定义 POJO 用 new TypeToken<MyPojo>(){}.getType() 重载。

Custom Token 签发

Users users = new Users(client);
Token token = users.createToken("<userId>", null, null);   // { secret, expire }
// 浏览器端用 Client SDK:account.createSession({ userId, secret: token.secret })

users.createJWT 是给用户签发短期 JWT(约 15 分钟)用于服务间带用户身份调用,不是 Session 通道;Tokens 服务是 Storage 文件临时令牌,与用户令牌无关。

功能面导航

服务面与 Node 面同构(PascalCase 类、驼峰方法),全量映射见 nodejs.md「功能面导航」;各功能页:数据库、存储、函数、站点、用户、团队、消息、记忆、知识库、LLM Gateway、AI Gateway、可观测、审核、横切服务。

Java 面特有差异:

与 Console SDK 并用

两个 SDK 的 Client 同名、namespace 独立(io.agentbase.Client vs io.agentbase.console.Client,见 ../console-sdk/java.md)。同一个 Java 文件只 import 一个,另一个用全限定类名;两边的 model / enum / service 禁止混用。

错误处理

try {
    tables.getRow("app-db", "tasks", rowId, null, null);
} catch (io.agentbase.exceptions.AppBaseException e) {
    System.err.println("HTTP " + e.getCode() + " type=" + e.getType() + " msg=" + e.getMessage());
    // 413 存储超限 / 429 限频 / 401·403 认证或 scope
}

示例指引

事实源