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:
Download URL: <https://code.alipay.com/obai/agentbase-sdks/releases/v2.12.0>
Artifacts: Server SDK ZIP, Console SDK ZIP, and a
SHA256SUMSchecksum fileRuntime: Java 11 source/target (runs on OpenJDK 11/17); the transport is OkHttp (the
lib/in the unpacked directory carries the runtime dependencies; if you use the JAR directly, you must shiplib/along with it)
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.pomThe 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 oneConsole 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 rulesCustom 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 getIngestionLLM 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/hybridWebhooks / 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.