Console SDK(Node.js / JavaScript)
The Console SDK targets management-plane callers: Console panel capabilities, organization and project governance, and cross-project operations automation, authenticated with a management identity—an email-password Session or a short-lived JWT. npm coordinate agentbase-console-sdk@2.10.0. See the same directory for the Java / Python / Go surfaces: java.md / python.md / go.md; for the browser frontend use the Client SDK; for the server-side data plane use the Server SDK.
Installation and initialization
npm install agentbase-console-sdk@2.10.0 --save-exactMethod One: sdk wrapper object (recommended; manages endpoints and modes automatically)
import { sdk, realtime } from 'agentbase-console-sdk';
sdk.forConsole.projects.list(/* Organization/Console-level calls */);
sdk.forConsoleIn('default').health.get(); // Specify region
sdk.forProject('default', '<projectId>').tablesDB.listRows(...); // Project resource plane; automatically calls setProject + setMode('admin')Method Two: bare Client (when fine-grained authentication control is needed)
import { Client } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('<consoleOrProjectId>'); // X-Appwrite-Project headerAuthentication loading (choose one of three; mutually exclusive):
Email-password Session: after
account.createEmailPasswordSession({ email, password }), load the session cookie (the automatic login flow intercepts the responseset-cookieandclient.setCookie(...)).Short-lived JWT:
client.setJWT(token)—short-lived credential; do not write to logs.SQL-scenario project API Key:
client.setProject('<应用项目ID>').setKey('<项目APIKey>')—used by the Sql service to point to the application project.
Other setters: setMode('admin'), setLocale, setSelfSigned.
5-minute quick start (management automation)
const projects = sdk.forConsole.projects;
const project = await projects.create({
projectId: 'unique()', name: 'My Project', teamId: '<teamId>', region: 'default',
});
const key = await projects.createKey(project.$id, 'server key', [
'users.read', 'users.write', 'teams.read', 'teams.write',
]);
// key.secret appears only once in the creation response; hand it to the server for secure storage immediatelyOn the server side, get a Key and integrate with the Server SDK; governance-plane tasks such as domain rules, migrations, and backups continue to use the services on this page.
Console-exclusive services
| Service | Covers |
|---|---|
Organizations | Administrative capabilities such as organization members and billing; instantiated separately by the Console Client as an export class, not on the sdk.forConsole wrapper object |
Proxy | Site/API/function/redirect domain rules (createSiteRule / listRules / getRule / updateRuleVerification / deleteRule) |
Vcs | Git integration: installations, repository discovery, branch lists, repository content, external deployment status write-back |
Migrations | Migration jobs (Appwrite/Firebase/Supabase/NHost/AppBase/CSV import-export): create, report, retry, delete; also includes SchemaMigration (a TablesDB-based schema planning/execution assistant) |
Assistant | assistant.chat() Management-side AI assistant |
Console | Platform metadata: listRegions / listTags, plan and resource queries, column/index suggestions (suggestColumns / suggestIndexes), variables |
Admin | Platform management: pool/label lists, storage migration, project table schema conversion, project deletion audit and recovery |
Activities / Backups / Domains | Event streams, backup policies and archives, domain assets |
Management-plane end-to-end walkthrough (create a project, issue a Key, register a Web platform, manage the lexicon, and execute SQL)
The following examples demonstrate using agentbase-console-sdk@2.10.0 in a Node.js management script to perform automated provisioning of an enterprise project (such as enterprise-ai-hub-210), registering the Web platform's CORS domain whitelist, creating and binding a project-level lexicon (Lexicons), and executing parameterized SQL queries via the Sql service exclusive to the Console SDK:
import { Client, Projects, Teams, Sql, ID, Scopes } from 'agentbase-console-sdk';
// 1. Initialize the management-plane Client (first point it at the console project to complete organization and project provisioning)
const consoleClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
.setJWT(process.env.APPBASE_ADMIN_JWT!); // or use setCookie / setSession to load an admin session
const teams = new Teams(consoleClient);
const projects = new Projects(consoleClient);
// 2. Create an organization (Team) and a Shared V2 enterprise project
const org = await teams.create({
teamId: '69c6d1aa00062e6bb60',
name: 'Agentbase 企业智能中台',
});
const project = await projects.create({
projectId: 'enterprise-ai-hub-210',
name: '企业智能客服与知识中台',
teamId: org.$id,
region: 'default', // Always pass 'default'; do not use the Appwrite Cloud region enum
});
// 3. Issue an API Key with a minimal permission set for backend services (the secret is returned only once, in the creation response)
const serverKey = await projects.createKey({
projectId: project.$id,
name: 'prod-backend-service-key',
scopes: [
Scopes.UsersRead,
Scopes.UsersWrite,
Scopes.TablesRead,
Scopes.TablesWrite,
Scopes.RowsRead,
Scopes.RowsWrite,
Scopes.KnowledgebasesRead,
Scopes.KnowledgebasesWrite,
],
});
console.log('请立即安全保存 API Key Secret:', serverKey.secret);
// 4. Register frontend Web platform domains (enables browser CORS trust; only Console Session/JWT can call)
await projects.createPlatform({
projectId: project.$id,
type: 'web',
name: 'Enterprise Support Portal',
hostname: 'support.enterprise.example.com',
});
// 5. Switch the Client to the target project and use the Sql service to execute parameterized queries (a capability exclusive to the JS Console SDK)
const projectSqlClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
.setProject(project.$id)
.setKey(serverKey.secret);
const sql = new Sql(projectSqlClient);
const queryResult = await sql.query({
databaseId: 'enterprise_biz_db',
query: 'SELECT ticketNo, title, status, priority FROM customer_tickets WHERE status = ? ORDER BY `$createdAt` DESC LIMIT ?',
params: ['open', 20],
});
console.log('SQL 命中行数:', queryResult.rowCount, '是否截断:', queryResult.truncated);
// 6. Project-level lexicon (Lexicons) management and knowledge base binding (the local development build provides the Lexicons class; published 2.10.0 packages use client.call)
await projectSqlClient.call('post', new URL(`${projectSqlClient.config.endpoint}/lexicons`), {
'content-type': 'application/json',
}, {
lexiconId: 'lex_enterprise_synonyms',
name: '企业核心产品同义词词典',
tokenizerProfile: 'native-v1',
});
await projectSqlClient.call('put', new URL(`${projectSqlClient.config.endpoint}/knowledgebases/kb_enterprise_support/lexicons`), {
'content-type': 'application/json',
}, {
enabled: true,
bindings: [
{ lexiconId: 'lex_enterprise_synonyms', priority: 1 },
{ lexiconId: 'lex_support_stopwords', priority: 2 },
],
});Selection comparison: Console SDK vs. Server SDK vs. Client Web SDK
| Dimension | Console SDK (agentbase-console-sdk@2.10.0) | Server SDK (agentbase-node-sdk@2.10.0) | Client Web SDK (agentbase-web-sdk@2.10.0) |
|---|---|---|---|
| Core positioning | Organization and project lifecycle governance, platform registration, domain rules, migrations, backups, SQL endpoint | Business backend data-plane reads/writes, user management, RAG knowledge base, memory, model gateway, and observability reporting | Browser-side user login sessions, RLS-protected data reads/writes, and Realtime subscriptions |
| Auth credentials | Admin Session Cookie / short-lived JWT (project API Key supported for SQL scenarios) | Project API Key (X-Appwrite-Key, bypasses RLS) | End-user Session Cookie / JWT (strictly enforces RLS row-level permissions) |
| Exclusive capabilities | Organizations, Projects.create/createKey/createPlatform, Proxy, Vcs, Migrations, Admin, Backups, Sql | Users.createToken (Custom Token issuance) and full project-level server-side batch processing | Account Browser OAuth redirect login, Realtime WebSocket subscriptions (shares realtime capabilities with Console) |
Versions and SDK support
The published npm coordinate is fixed as
agentbase-console-sdk@2.10.0(and the internal mirror@alipay/agentbase-console-sdk@2.10.0); see ../integration.md for installation verification details.Lexicon management can be performed via REST interfaces (including
/v1/lexicons,/v1/lexicons/{lexiconId}/entries,/v1/lexicons/{lexiconId}/preview,/v1/lexicons/{lexiconId}/import,/v1/lexicons/{lexiconId}/export,/v1/lexicons/{lexiconId}/references,/v1/knowledgebases/{knowledgeBaseId}/lexicons, and/v1/agent-runtime/agents/{agentId}/lexicons); in the published2.10.0npm package, these REST paths can be called directly viaclient.call.
Functional surface navigation (governance domain → services)
| Domain | Services and method highlights | Feature documentation |
|---|---|---|
| Organization | Organizations: members, billing address, invoices, top-ups, organization Keys, listUsageAggregates({ organizationId }); instantiated by new Organizations(client) | ../organization.md, ../usage.md |
| Project lifecycle | Projects.create({ projectId, name, teamId, region: 'default', poolTag }) / get / update / delete / list | ../overview.md |
| Project Keys and platforms | projects.createKey (scope as a lowercase dot-separated string; secret visible only at creation time), createDevKey, createPlatform / listPlatforms (Console Session only), updateOAuth2 | ../overview.md |
| Quotas and rate limits | Project projects.getQuotaLimits / updateQuotaLimits; account account.getQuotaLimits / updateQuotaLimits / deleteQuotaLimits (no listLimitsProjects); /limits via client.call | ../limits.md |
| Three-level usage | sdk.forConsole.account / sdk.forConsole.projects and the standalone Organizations service's listUsageAggregates() (the most recent 30 UTC days) | ../usage.md |
| Project resource plane | TablesDB / Sql / Sites / Functions / Storage / Messaging / Memory (including project configuration and rollback) / Users / Teams / Tokens / LLMGateway (including usage) / Webhooks / Graphql / Avatars / Locale / Health | Feature pages (../misc/webhooks.md, etc.) |
| SQL | Sql.query / Sql.execute (exclusive to the JS Console SDK; for the Java / Python / Go Console surfaces see each page's notes) | ../databases/sql-proxy.md |
| Sites and domains | Sites full set + Proxy domain rules + Domains | ../sites.md |
| Realtime | realtime.forProject(region, channels, cb) / realtime.forConsole(...) | ../realtime.md |
| Platform operations | Admin / Backups / Activities / Health (including management-plane queue checks) | ../misc/webhooks.md |
Errors and boundaries
Error model:
AppBaseException(code/type).Platform registration (
createPlatform) and organization queries are Console-only operations and cannot use project API Keys; for project resource operations, it is recommended to proceed aftersetProject(应用项目).The Console Session cookie and OAuth test Sessions are mutually isolated; JWTs are valid short-term and must be re-issued after expiration.
Example Guide
JavaScript Console initialization and typical calls: ../examples/javascript.md