agentbase-docs

Java 示例

Java Server SDK 与 Console SDK 以 ZIP 交付包发布(不发布到 Maven Central/内部 registry),托管在 agentbase-sdks release v2.8.0:

获取与校验

# 1. 下载 ZIP 与校验文件(curl 或浏览器)
curl -LO <release 页面中的 Server SDK ZIP 地址>
curl -LO <release 页面中的 Console SDK ZIP 地址>
curl -LO <release 页面中的 SHA256SUMS 地址>

# 2. 校验完整性
sha256sum -c SHA256SUMS --ignore-missing
unzip agentbase-java-sdk-2.8.0.zip && unzip agentbase-console-java-sdk-2.8.0.zip
# 解包目录内如再有 SHA256SUMS,进入后再次 sha256sum -c SHA256SUMS

# 3. 安装到本地 Maven 仓库(或确认团队仓库已提供同 GAV)
mvn install:install-file -Dfile=agentbase-java-sdk-2.8.0.jar -DpomFile=agentbase-java-sdk-2.8.0.pom
mvn install:install-file -Dfile=agentbase-console-java-sdk-2.8.0.jar -DpomFile=agentbase-console-java-sdk-2.8.0.pom

ZIP 与 JAR 的确切文件名以 release v2.8.0 页面实际资产为准;不要凭记忆拼文件名。

依赖声明(maven.compiler.release 11+):

<dependency>
  <groupId>io.agentbase</groupId>
  <artifactId>agentbase-java-sdk</artifactId>
  <version>2.8.0</version>
</dependency>
<dependency>
  <groupId>io.agentbase.console</groupId>
  <artifactId>agentbase-console-java-sdk</artifactId>
  <version>2.8.0</version>
</dependency>

Server SDK 初始化

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);               // 服务逐个构造

Console SDK 初始化

import io.agentbase.console.Client;
import io.agentbase.console.services.Projects;

Client consoleClient = new Client()
    .setEndpoint("https://appbuild.oceanbase.com/v1")
    .setProject(System.getenv("APPBASE_CONSOLE_PROJECT_ID"));  // Console 项目,常为 console

// 凭据三选一(互斥):
consoleClient.setKey("<Console API Key>");     // 服务端自动化首选
// consoleClient.setJWT("<短期 JWT>");
// consoleClient.setSession("<Console 会话 Cookie>");

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

TablesDB(建库表、行、查询)

import io.agentbase.models.DatabaseColumnDefinition;
import io.agentbase.models.DatabaseIndexDefinition;
import io.agentbase.enums.DatabaseSchemaType;
import io.agentbase.enums.DatabaseSchemaIndexType;
import java.util.List;
import java.util.Map;

tables.create("app-db", "App", null, true, null, null, null, null, null, null, null, null);

tables.createTable(
    "app-db", "tasks", "Tasks",
    null,                                  // permissions
    true,                                  // rowSecurity
    true,                                  // enabled
    List.of(new DatabaseColumnDefinition()
        .setKey("title").setType(DatabaseSchemaType.VARCHAR)
        .setSize(256L).setRequired(true)),
    List.of(new DatabaseIndexDefinition()
        .setKey("title_idx").setType(DatabaseSchemaIndexType.KEY)),
    null                                   // comment
);

tables.createRow("app-db", "tasks", ID.unique(),
    Map.of("title", "写周报"), null, null);

var rows = tables.listRows("app-db", "tasks",
    List.of(Query.equal("done", false), Query.orderDesc("$createdAt"), Query.limit(25)),
    null, true, null);

Storage / Functions

Storage storage = new Storage(client);
storage.createBucket("attachments", "附件", null, true, true,
    26214400L, null, null, true, false, true);
storage.createFile("attachments", ID.unique(),
    InputFile.fromPath(java.nio.file.Paths.get("./report.pdf")), null);

Functions functions = new Functions(client);
Execution exec = functions.createExecution("send-mailer",
    "{\"to\":\"a@b.c\"}", false, "/", ExecutionMethod.POST, null, null);
// 异步执行后用 functions.getExecution(functionId, executionId) 轮询

Sites(位置参数全集,绝大多数可空)

Sites sites = new Sites(client);
sites.create("portal", "用户门户", Framework.REACT, BuildRuntime.NODE_22,
    true, true, 30L,
    "npm install", "npm run build", "", "dist",
    Adapter.STATIC,
    null, "index.html",           // installationId, fallbackFile(SPA 必备)
    null, null, false, null,      // VCS 相关
    null, null, null, null, null); // 规格/执行计划/保留期,见 listSpecifications()
// 部署:sites.createDeployment(siteId, code, activate, ...) 后轮询 getDeployment;
// 用本次 deploymentId 经 Proxy 规则解析预览 URL

Custom Token(服务端签发 → 客户端换 Session)

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

Memory / Knowledge Bases

Memory memory = new Memory(client);
memory.create(Map.of(
    "userId", userId,
    "scope", "user",
    "memoryType", "long_term",
    "recordKind", "fact",
    "content", "我喜欢简洁的回复",
    "infer", true));

KnowledgeBases kb = new KnowledgeBases(client);
KnowledgeBase base = kb.create(ID.unique(), "产品手册", "text-embedding-v3",
    null, null, null, null, null, null, null);
kb.createIngestion(base.getId(), docId, null, null, null, null);   // 异步:轮询 getIngestion

LLM Gateway / AI Gateway / Observability / Moderation

LlmGateway llm = new LlmGateway(client);
Object chat = llm.createChatCompletion(
    "qwen-max",
    List.of(Map.of("role", "user", "content", "用一句话介绍 TablesDB")),
    0.2, 300L, false, null, null);

AiGateway aiGateway = new AiGateway(client);
aiGateway.listKeys();   // Consumer/Policy/Target/Tool 控制面同名方法见源码
// 数据面推理/MCP/A2A 走 HTTP:/ai-gateway/g/{gatewayId}/v1 | /mcp | /a2a/{targetSlug}

Observability observability = new Observability(client);
observability.createIngestion(
    List.of(Map.of(
        "id", java.util.UUID.randomUUID().toString(),   // 外层幂等 ID
        "timestamp", java.time.Instant.now().toString(),
        "type", "trace-create",
        "body", Map.of("id", traceId32Hex, "name", "agent-run"))),
    null);
// 全部成功 HTTP 200;部分失败 HTTP 207 —— 逐项检查 errors[],不能只看是否抛异常

Moderation moderation = new Moderation(client);
moderation.createConfig(ResourceType.COLLECTIONS, "tasks", Mode.PRE,
    List.of("text"), "app-db", true);

Webhooks / Console 用量

Webhooks webhooks = new Webhooks(client);
webhooks.create(ID.unique(), "https://example.com/hook", "notify",
    List.of("databases.*.tables.*.rows.*.create"), true, true, null, null);

// 三级用量(最近 30 个 UTC 日):Java Console SDK 生成名是 getUsageAggregates
new io.agentbase.console.services.Projects(consoleClient)
    .getUsageAggregates("<projectId>");
new io.agentbase.console.services.Project(consoleClient)
    .getUsage(null, null, null);   // 旧口径 /project/usage

错误处理与类型

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
}

方法默认返回类型化 model 或 Map<String,Object>;自定义 POJO 用 new TypeToken<MyPojo>(){}.getType() 重载。Java Console SDK 没有 Sql 服务(SQL 走 HTTP 形态或 JS Console SDK),也没有 typed 的 quota/ratelimit 方法(见 limits.md 的 REST 入口)。

事实源