Docs
Contents

Core Concepts

Agentbase is built on rigorous multi-tenant resource isolation, dual-plane identity authentication, and the OceanBase distributed storage engine. Whether using basic Auth, Databases, Storage, and Functions, or orchestrating enterprise-grade LLM gateways, hybrid retrieval knowledge bases, long-term memory, and the agent workspace, all resources follow unified hierarchical ownership, ID conventions, permission expressions, and secure default boundaries.

Organization members page (reusing the registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

Feature Overview

When enterprises develop agent applications collaboratively across multiple teams and multiple environments (development / staging / production), architects and developers need clarity on four core foundational questions:

  1. Resource ownership and physical isolation: how are team members, billing quotas, business databases, and AI knowledge assets isolated in layers by organization and project? What is the essential difference between OceanBase's JsonTable and Shared V2 storage modes?

  2. Dual-plane identity and credential boundaries: in what scenarios are developer sessions in the management Console (Console Session), API Keys for backend microservices, and end-user login sessions on the frontend (Client Session / JWT) used respectively? How are permissions validated?

  3. Resource identifiers and fine-grained ACL: how is the $id of business documents, data rows, storage files, and knowledge base entries generated? How can read, create, update, delete, and write be combined with the role selector to implement row-level and object-level access control?

  4. AI-Native Primitives Collaboration: How do the LLM Gateway, AI Gateway, Knowledge Base & Lexicon, Memory, Agent Runtime Workbench, and AgentOps coordinate around the Project context?

This chapter systematically breaks down the core concepts above, serving as the design and troubleshooting foundation for each functional module throughout the book.

Core Concepts and Architecture

Agentbase's global architecture consists of three-tier resource containers (Account → Organization → Project), a dual-plane auth gateway (Control Plane vs Data Plane), a dual-mode storage engine (JsonTable vs Shared V2), and six AI-native primitives.

Core Concepts: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

1. Three-Tier Resource Hierarchy and Project Storage Modes (JsonTable vs Shared V2)

All resources in Agentbase are mounted under explicit hierarchy nodes; there is no business data or key that exists outside a project:

  1. Account: The identity entity with which a human developer logs in at /console/login, maintaining personal email, password, external linked identities (GitHub / enterprise SSO), multi-factor authentication (MFA with one-time recovery codes), and account-level aggregated usage over the last 30 UTC days.

  2. Organization: The top-level container for team collaboration and resource governance (e.g., Agentbase 企业智能中台, ID: 69c6d1aa00062e6bb60). An organization can contain multiple Projects (e.g., development, staging, and production environment projects), controls members' read/write permissions in the Console through 6 organization roles, and provides organization-level bulk cleanup of inactive projects (Project cleanup).

  3. Project: The strongly isolated resource boundary for application backends and AI capabilities (e.g., 企业智能客服与知识中台, ID: enterprise-ai-hub-210). Each project determines its underlying OceanBase table storage mode at creation or in settings:

Storage mode dimensionShared table / dedicated table (traditional mode / JsonTable compatible)OceanBase Shared V2 mode (recommended baseline for enterprise-grade AI)Deep Dedicated table mode
Physical storage structureCarries business documents based on generic metadata collections and JSON attribute column mappingA Shared V2 table structure deeply optimized for multi-tenant high concurrency and vector/hybrid workloadsAllocates a physically deep-isolated storage space for a single ultra-high-throughput table
Online table mode conversionSupports conversion to/from dedicated tables in project Settings → project table mode (with blocking when relationship collections exist)Supports direct adoption for new projects, or migration via conversion tasks when constraints are metDoes not support online conversion to other table modes
AI Memory long-term memory supportNot supported (calling Memory initialization returns HTTP 412)Natively supported (mandatory prerequisite for Memory fact extraction, profiling, and experience/skill distillation)Depends on platform-specific configuration; general projects are recommended to use Shared V2
Applicable business scenariosLightweight traditional CRUD prototypes or pure document-based legacy applicationsEnterprise-grade agent applications, intelligent customer service middle platforms, and RAG + Memory integrated production projectsSpecial core accounting tables with ultra-large single-table write volume and no cross-mode conversion needs

2. Dual-Plane Authentication Model (Dual-Plane Auth)

Agentbase strictly separates control-plane administrative identities from data-plane business identities, and further subdivides the data plane into server-side privileged calls and client-side restricted calls:

Auth credential typeApplicable callerCore request headersPermission determination mechanismSubject to row-level/file-level ACL
Console Session (developer session)Developer operating in a /console/ browser, or using the Console SDKCookie session + X-Appwrite-Mode: admin + X-Appwrite-ProjectDetermined by the developer's member role in the Organization that owns the project (owner / admin / developer / editor vs read-only billing / analyst)No (has an administrative perspective; granted per organization role)
Server API Key (server-side key)Enterprise backend microservices, scheduled jobs, external Agent orchestrators, internal Function callsX-Appwrite-Project: <PROJECT_ID> + X-Appwrite-Key: standard_...Determined by the Scopes (permission scopes, e.g., users.read, databases.write) selected when creating the API Key; also unaffected by disabling project Services client switchesNo (can read/write all project resources across users within authorized Scopes; business ownership must be controlled in the backend)
Client Session / JWT (end-user credential)End-user clients such as web browsers, iOS/Android apps, and mini-programs (Web SDK)X-Appwrite-Project: <PROJECT_ID> + Session Cookie or X-Appwrite-JWT: <JWT>1. The request origin must match a registered Platform (Hostname / Bundle ID);
2. The target service must be enabled in Settings → Services;
3. Strictly validated against the Permissions ACL of the target table/row/bucket/file
Yes (can only access resources explicitly granted via any, users, user:{id}, or team:{id} membership)
Dev Key (development/debugging key)Local development and debugging environments (e.g., debugging the frontend SDK at localhost)X-Appwrite-Project + X-Appwrite-Dev-Key: <DEV_KEY>Only used in development environments to temporarily bypass request rate limits (Ratelimit) and browser CORS checks, and to return detailed error stacks; valid for up to 30 daysYes (does not elevate data access permissions; still follows the ACL rules of the current client identity)

3. Resource Identifiers ($id) and Permission Expressions (Permissions & Roles)

In Agentbase, everything — projects, databases, tables, rows, buckets, files, knowledge bases, lexicons, gateways, and evaluation sets — uses a two-layer identifier design:

For tables (Table / Row), buckets (Bucket / File), function execution (Function Execute), and message topics (Topic Subscribe), Agentbase adopts a unified Action + Role Selector permission model and adheres to Deny by Default: if no permission entry is configured, no client end user has access; only server-side API Keys and Console administrators can access.

Permission dimensionSyntax formatPrecise semantics and scope of applicationProduction configuration example (intelligent customer service support ticket scenario)
Actionsread("<role>")Allows reading rows, downloading/previewing files, or viewing resource metadataread("user:user_zhangwei_001") (allows customer Zhang Wei to view his own support ticket)
create("<role>")Allows adding new rows to a table or uploading new files to a bucket (configured at table or bucket level)create("users") (allows all logged-in customers to submit new support tickets)
update("<role>")Allows modifying existing rows or updating file metadata (excluding deletion)update("team:support_tier2/agent") (allows tier-two customer service agents to update support ticket status)
delete("<role>")Allows deleting rows or stored filesdelete("team:support_tier2/owner") (only customer service supervisors can delete support tickets)
write("<role>")create Shorthand alias combining update + delete +write("team:kb_editors") (allows the knowledge base editing team to create, delete, and modify documents)
Role SelectorsanyAny requester (including anonymous unauthenticated visitors and logged-in users)Public knowledge base attachment bucket configuration read("any")
guestsOnly unauthenticated anonymous session visitorsAnonymous feedback table configuration create("guests")
users / users/verifiedAny logged-in end user / only logged-in users who have completed email or phone verificationEnterprise internal Q&A community configuration read("users/verified")
user:{userId}A single end user with the specified unique $id (optionally appended with /verified)Support ticket row-level permission read("user:user_zhangwei_001")
team:{teamId} / team:{teamId}/{role}All members of a specified team / only members with a specific custom role within that team (e.g., owner, agent)Tier-two technical support team read("team:ob_dba_team/specialist")
label:{label}All users with a specified user label (User Label, applied by the server or administrators to Auth users, e.g., vip, internal)VIP-exclusive service channel configuration create("label:vip")

4. Six AI-Native Primitives and Their Collaboration Mechanism

Agentbase abstracts the core infrastructure required to build production-grade agents into six primitives, which collaborate organically within the project enterprise-ai-hub-210:

  1. LLM Gateway (model gateway /llm-gateway): Manages model provider credentials (e.g., Alibaba Cloud Bailian dashscope-prod) and the model capability catalog (Chat qwen-plus / qwen-turbo, Embedding text-embedding-v3 1024 dimensions, Rerank qwen3.7-text-rerank, Vision qwen-vl-max), and issues Gateway Keys supporting monthly Token budgets and RPM/TPM rate limiting.

  2. AI Gateway (unified AI gateway /ai-gateway): The governance plane for complex production traffic (e.g., prod-enterprise-ai-gateway gw_7194685489feb1e169548619), providing logical model routing (lm-enterprise-chat primary/backup failover and weighted traffic splitting), input/output safety guardrails (gp-enterprise-safety), semantic caching (cp-semantic-cache), and MCP tool/agent registration governance.

  3. Knowledge Base & Lexicon /knowledge-base): Parses and chunks unstructured documents from Storage, vectorizes them (validating consistency with the 1024 dimensions locked to the knowledge base), and stores them in the OceanBase hybrid index; retrieval accuracy is optimized by binding synonym lexicons (lex_enterprise_synonyms) and stopword lexicons (lex_support_stopwords), with support for building GraphRAG (entity-relation-community reports), RAPTOR (recursive clustering summary trees), and LLM Wiki (compiled encyclopedia pages with citation traceability).

  4. Memory & PowerContext (long-term memory and managed context /memory · /powercontext): Within an Shared V2 project, asynchronously extract user factual memory from multi-turn conversations, images, or PDFs, generate user profiles, aggregate layered context (Context Dreaming), and distill reusable experience and skills from high-frequency successful trajectories (Experience/Skill Distillation, such as dst_3e5b09f456c5d5c332507ec1dbe3eb6d). Supports four types of Pipeline with draft verification and publishing plus secondary manual confirmation.

  5. Agent Runtime Workbench (agent workbench /agent-runtime): Provides a no-code/low-code agent assembly and streaming conversation debugging environment. Supports persisting the main conversation model, system prompt, multiple knowledge bases, and intervention lexicon as project-level configuration (/v1/agent-runtime/project/config), and supports direct invocation at runtime by the server via the project API Key.

  6. Observability / AgentOps (agent operations /observability): Collects full-link Traces and Observations for every agent inference, tool call, RAG retrieval, and memory read/write. Provides general evaluation, Memory evaluation, knowledge base parsing and chunking evaluation, as well as GraphRAG / RAPTOR / LLM Wiki knowledge index quality evaluation.

Roles, Entry Points, and Relationships

1. Organization-Level and Project-Level Console Navigation Entrances

Governance tierCore operation modulesConsole route pathMinimum required organization role
Account level (Account)Personal profile, MFA and recovery codes, global sessions, pending-cleanup project recovery, table mode conversion history/console/accountAny registered and logged-in Console account
Organization level (Organization)Project list, member invitations and role assignment, 30-day organization aggregate usage, batch cleanup of inactive projects/console/organization-{organization}/members etc.View: any member; invite/manage: owner or admin; delete organization/clean up projects: owner
Project level (Project)Platform registration, API Key management, service toggles, table mode conversion, business and AI module configuration/console/project-{region}-{project}/*View: any member; create/modify resources: owner / admin / developer / editor

2. Platform-Level Security Default Behaviors (Security by Default)

To guard against the privilege escalation, injection, and intranet probing risks common in enterprise production environments, Agentbase enforces non-bypassable security default policies at the underlying execution layer:

Security domainPlatform-enforced default behaviorPractical impact on development and operations
Outbound network and SSRF protectionRejects access to local loopback (127.0.0.0/8), RFC1918 private network addresses, link-local addresses, and cloud vendor metadata addresses (169.254.169.254)Webhook target URLs, remote OAuth2 endpoints, model provider custom endpoints, and function/site outbound requests are all protected by the SSRF guard.
Restricted identity for cloud functions and sitesFunctions and Sites containers always run as a non-privileged restricted system identity (Restricted Identity)If deployment scripts or startup commands do not meet the restricted security conditions, the system fails immediately with an error and never silently falls back to root elevated privileges.
Function call credential transmissionPassing Function API Keys via URL query string is strictly forbiddenTriggering protected functions must go through HTTP Headers (such as X-Appwrite-Key) or platform-injected runtime identity authentication, preventing credentials from being recorded in plaintext by proxies or access logs.
Storage image moderation fail-closedPrivate storage buckets with image content moderation enabled adopt a fail-closed policyOnce an image is flagged as violating policy (block/review), exceeds the size limit, or the moderation service call errors, the uploaded object is immediately and physically purged, with no unreviewed copies retained.
Database schema activation validationBefore activating a new schema version, consistency of the underlying OceanBase physical table structure is mandatorily validatedIf physical structure validation fails, the activation is aborted immediately while the currently live version continues serving, preventing metadata and physical column desynchronization.
Distributed transaction connection recoveryNon-transactional idempotent read requests support automatic reconnection recovery when connections drop; explicit transaction requests are never automatically replayedWhen a network interruption occurs during transaction execution, the caller must first confirm the transaction's final state via the business unique key, then decide whether to retry according to the idempotency policy.
One-way masking of sensitive credentialsOAuth2 Client Secrets, model provider API Keys, moderation AK/SK, and global Secret variables are write-only and never echoed backAfter saving, they are encrypted server-side, and the Console displays only masks; API Key Secrets are visible only to project owner, the creator, and privileged roles.

Feature Details and Operation Guide

This section uses three core governance hands-on scenarios to demonstrate how to view and manage organization member roles in the Console, verify project storage mode and service toggles, and configure fine-grained ACL permissions for business resources.

1. Verifying Organization Member Roles and 2FA Security Status

  1. After logging into the Console, select Agentbase 企业智能中台 (69c6d1aa00062e6bb60) in the top organization switcher, click Members in the top tab bar, and go to /console/organization-69c6d1aa00062e6bb60/members (as shown in Figure 1).

  2. In the member list table, verify each member's Name, Email, 2FA (two-step verification enablement status), and Roles (organization roles).

  3. Click Invite (invite members) in the upper-right corner. In the popup, fill in the invitee's email and display name in turn, and check roles in the role dropdown according to responsibilities (e.g., assign Developer to algorithm engineers, Editor to knowledge operations staff, and Billing to finance personnel).

  4. For existing members, click the row-end action menu ⋮ → Edit role to adjust their role scope instantly; once saved, the adjustment takes effect immediately on all of that member's subsequent Console and management-plane requests.

2. Checking and Managing Project Table Storage Mode and Client Service Toggles

  1. In the organization project list, click into 企业智能客服与知识中台 (enterprise-ai-hub-210), and click Settings at the bottom of the left navigation bar.

  2. Under the Overview tab, find the Table Mode card:

    • Confirm that the current project runs in Shared V2 mode (this is the standard foundation for enabling the AI Memory long-term memory service and high-performance mixed workloads).

    • To convert legacy shared tables to exclusive tables or Shared V2, first ensure the project contains no collections of type relationship; after submitting the conversion, you can track the asynchronous conversion progress under the Account → Table mode conversions tab.

  3. Scroll down to the Services card:

    • Check the start/stop toggles of each service facing client SDKs (such as Account, Databases, Storage, Functions, Memory, Knowledge Bases, AI Gateway).

    • If you plan to use the unified AI Gateway in the project, toggle the AI Gateway switch to on here, which immediately unlocks the AI Gateway navigation item in the left sidebar.

3. Configuring Resource-Level and Row-Level Permissions (ACL) on Data Tables and Storage Buckets

Taking the customer support ticket table customer_tickets under the business database enterprise_biz_db as an example, implement the policy where any logged-in customer can submit support tickets, but only the ticket creator and the second-line customer support team can view and modify the ticket:

  1. Go to the left sidebar Databases → click database enterprise_biz_db → click data table customer_tickets → switch to the Settings tab.

  2. In the Permissions (table-level permissions) area:

    • Click Add role → select All users (users), and check only Create (allowing any logged-in end user to create ticket rows, but do not check the table-level Read, preventing ordinary users from listing other users' tickets across the table).

    • Click Add role again → select Team, enter the customer support team ID (e.g., support_team), and check Read and Update (allowing customer support team members to read and process all tickets).

  3. Enable Row security (row-level security toggle) and click Update to save.

  4. When the client or server inserts a specific ticket row (e.g., TK-20261022-001, owned by customer user_zhangwei_001), write read("user:user_zhangwei_001") and update("user:user_zhangwei_001") into that row's permission array to achieve precise row-level tenant isolation.

Security Defaults

DomainDefault behavior
External URLsReject local, private network, and cloud metadata addresses (SSRF protection)
Function / SiteRun under restricted identity; fail immediately when security conditions are not met, with no fallback to elevated execution
Console SQLDo not display MySQL wire direct-connection information in the browser
Schema changesValidate physical structure before activation; on failure, keep the currently live version serving
SQL Proxy transactionsNo public transaction status; transaction control commands are rejected; unconfirmed write results should be read back first and handled according to the idempotency policy
Storage moderationPrivate image moderation fails closed; on failure, uploads are cleaned up
Login stateSingle-use, bound to project / browser / callback / Client ID / state revision
Test sessionsSessions created by OAuth login testing are isolated from Console sessions; logging out of a test does not log out of the Console
Function API KeyNo longer accepted via query string; use protected headers or platform-injected runtime authentication paths

FAQ and Troubleshooting

Q1: Why does querying a data table with the frontend Web SDK return an empty array [], while querying with the backend API Key returns 4 ticket records?

Cause and troubleshooting steps: This is the most typical manifestation of dual-plane permission differences, not data loss:

  1. Backend requests carry X-Appwrite-Key: standard_... (Server API Key). As long as the Key has rows.read / databases.read scope, it can bypass table-level and row-level ACLs to read all data.

  2. The frontend Web SDK carries the end user's session, which is strictly restricted by table-level Permissions and row-level Row security. If the user has not been granted read permission at the table level, and the row itself also lacks read("user:{userId}") (or the row security toggle rowSecurity is not enabled), the server silently filters out rows the user has no access to, ultimately returning an empty list []. Please check the permission configuration under the data table's Settings → Permissions and the specific data row detail page.

Q2: Why do members with organization roles Billing or Analyst get errors when clicking save or create buttons in the Console?

Cause and troubleshooting steps: In Agentbase's RBAC model, Billing (billing/finance) and Analyst (data analyst) are strictly read-only roles. They can browse project overviews, usage aggregates over the last 30 UTC days, observability traces, and evaluation reports, but the underlying management-plane API intercepts all write operations (which require owner, admin, developer, or editor roles). If such a member needs to create knowledge bases, modify prompts, or generate API Keys, please have an organization Owner or Admin upgrade their role to Editor or Developer on the Organization → Members page.

Q3: Why can't I perform operations when enabling Column deletion in project Settings or preparing a table mode conversion?

Cause and troubleshooting steps: