Docs
Contents

Java Example

The Java Server SDK and Console SDK are distributed as ZIP deliverables (not published to Maven Central or an internal registry), hosted on agentbase-sdks release v2.12.0:

Retrieval and Verification

# 1. Download the ZIP and checksum file (curl or browser)
curl -LO <release 页面中的 Server SDK ZIP 地址>
curl -LO <release 页面中的 Console SDK ZIP 地址>
curl -LO <release 页面中的 SHA256SUMS 地址>

# 2. Verify integrity
sha256sum -c SHA256SUMS --ignore-missing
unzip agentbase-java-sdk-2.12.0.zip && unzip agentbase-console-java-sdk-2.12.0.zip
# If another SHA256SUMS appears inside the unpacked directory, enter it and run sha256sum -c SHA256SUMS again

# 3. Install into the local Maven repository (or confirm the team repository already provides the same GAV)
mvn install:install-file -Dfile=agentbase-java-sdk-2.12.0.jar -DpomFile=agentbase-java-sdk-2.12.0.pom
mvn install:install-file -Dfile=agentbase-console-java-sdk-2.12.0.jar -DpomFile=agentbase-console-java-sdk-2.12.0.pom

The exact file names of the ZIP and JAR artifacts follow the actual assets on the release v2.12.0 page; do not assemble file names from memory.

Dependency declaration (maven.compiler.release 11+):

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

Server SDK initialization

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"));        // Project API Key with minimal scope
client.setHttpClient(new okhttp3.OkHttpClient.Builder()
    .followRedirects(false).followSslRedirects(false).build());

TablesDB tables = new TablesDB(client);               // Construct services one by one

Console SDK initialization

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

Client consoleClient = new Client()
    .setEndpoint(System.getenv("APPBASE_ENDPOINT")) // Includes /v1
    .setProject("console")
    .setCookie(System.getenv("APPBASE_SESSION_COOKIE")); // Full Cookie header value

// A short-lived Console JWT can replace the Cookie; do not load multiple credential types at once.
// consoleClient.setJWT(System.getenv("APPBASE_CONSOLE_JWT"));

On the same classpath, used together: the two SDKs share Client names but have independent namespaces (io.agentbase.Client vs io.agentbase.console.Client). In a single Java file, import only one and use the fully qualified class name for the other; model / enum / service types from the two sides must not be mixed.

Management-plane calls remain subject to organization member roles; an ordinary project API Key cannot replace Console Session/JWT. For differences in authentication and governance methods, see Console Java SDK.

TablesDB (Databases, Tables, Rows, Queries)

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", true);              // enabled

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),
        new DatabaseColumnDefinition()
            .setKey("done").setType(DatabaseSchemaType.BOOLEAN).setRequired(true)),
    List.of(new DatabaseIndexDefinition()
        .setKey("title_idx").setType(DatabaseSchemaIndexType.KEY)
        .setAttributes(List.of("title"))),
    null                                   // comment
);

tables.createRow("app-db", "tasks", ID.unique(),
    Map.of("title", "写周报", "done", false), 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

import io.agentbase.ID;
import io.agentbase.enums.ExecutionMethod;
import io.agentbase.models.Execution;
import io.agentbase.models.InputFile;
import io.agentbase.services.Functions;
import io.agentbase.services.Storage;

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

Functions functions = new Functions(client);
Execution exec = functions.createExecution("send-mailer",
    "{\"to\":\"a@b.c\"}", true, "/", ExecutionMethod.POST, null, null);
Execution current = functions.getExecution(exec.getFunctionId(), exec.getId());
// async=true: query repeatedly at intervals until the status is COMPLETED or FAILED.

Sites (Complete Positional Parameter Set, Most Are Nullable)

import io.agentbase.enums.Adapter;
import io.agentbase.enums.BuildRuntime;
import io.agentbase.enums.Framework;
import io.agentbase.services.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 (required for SPA)
    null, null, false, null,      // VCS-related
    null, null, null, null, null); // Specifications / execution plan / retention period, see listSpecifications()
// Deployment: after sites.createDeployment(siteId, code, activate, ...), poll getDeployment;
// Use this deploymentId to resolve the preview URL via the Proxy rules

Custom Token (Server-Side Issuance → Client Session Exchange)

Users users = new Users(client);
Token token = users.createToken("<userId>", null, null);   // { secret, expire }
// Use the Client SDK in the browser: account.createSession({ userId, secret: token.secret })

Memory / Knowledge Bases

Memory memory = new Memory(client);
memory.create(userId, io.agentbase.enums.MemoryScope.USER, "preference",
    io.agentbase.enums.RecordKind.FACT,
    null,                                  // pipelineId
    "我喜欢简洁的回复", null,               // content, messages
    null,                                  // media
    null, null, null,                      // agentId, runId, sessionId
    null, null, null, null,                // sensitivity, handlingPolicy, metadata, sourceContext
    false, null, false);                   // infer, reRemember, async
// Deterministic direct write; model extraction uses infer=true, and check the async result.

KnowledgeBases kb = new KnowledgeBases(client);
KnowledgeBase base = kb.create(ID.unique(), "产品手册", "text-embedding-v3",
    null, null, null, null, null, null, null, null, null); // description through tracingEnabled
kb.createIngestion(base.getId(), docId, null, null, null, null, null); // Asynchronous: poll 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 control-plane methods of the same names, see source code
// Tool data plane uses HTTP: /ai-gateway/g/{gatewayId}/mcp | /a2a/{targetSlug}; use LLM Gateway for model calls

// The project-level agent workbench (/v1/agent-runtime/project/*) is accessed via a Project API Key (agent-runtime.project) + userId; for a full example see ../agent-runtime.md
Observability observability = new Observability(client);
observability.createIngestion(
    List.of(Map.of(
        "id", java.util.UUID.randomUUID().toString(),   // Outer idempotency ID
        "timestamp", java.time.Instant.now().toString(),
        "type", "trace-create",
        "body", Map.of("id", traceId32Hex, "name", "agent-run"))),
    null);
// All succeed: HTTP 200; partial failure: HTTP 207 — check errors[] item by item; do not rely only on whether an exception is thrown

Moderation moderation = new Moderation(client);
moderation.createConfig(ResourceType.COLLECTIONS, "tasks", Mode.PRE,
    List.of("text"), "app-db", true, null); // requireManualReviewOnViolation is only for post/hybrid

Webhooks / Console Usage

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

// Three-level usage (last 30 UTC days): the generated name in the Java Console SDK is getUsageAggregates
new io.agentbase.console.services.Projects(consoleClient)
    .getUsageAggregates("<projectId>");
// The legacy /project/usage requires a business project context; see the Console Java SDK "usage query" example.

Error Handling and Types

try {
    tables.getRow("app-db", "tasks", rowId, null, null);
} catch (io.agentbase.exceptions.AgentbaseException e) {
    System.err.println("HTTP " + e.getCode() + " type=" + e.getType() + " msg=" + e.getMessage());
    // 413 storage quota exceeded / 429 rate limited / 401·403 authentication or scope
}

Methods return a typed model or Map<String,Object> by default; custom POJOs use the new TypeToken<MyPojo>(){}.getType() overload. The Java Console SDK has no Sql service (SQL goes through the HTTP form or the JS Console SDK). Project quotas and rate limits provide typed Projects.getQuotaLimits / updateQuotaLimits / getLimits / updateLimits / deleteLimits; for initialization and calls, see Console Java; for field semantics, see Limits and Quotas.