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.
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:
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
JsonTableandShared V2storage modes?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?
Resource identifiers and fine-grained ACL: how is the
$idof business documents, data rows, storage files, and knowledge base entries generated? How canread,create,update,delete, andwritebe combined with the role selector to implement row-level and object-level access control?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.
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:
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.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).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 dimension | Shared table / dedicated table (traditional mode / JsonTable compatible) | OceanBase Shared V2 mode (recommended baseline for enterprise-grade AI) | Deep Dedicated table mode |
|---|---|---|---|
| Physical storage structure | Carries business documents based on generic metadata collections and JSON attribute column mapping | A Shared V2 table structure deeply optimized for multi-tenant high concurrency and vector/hybrid workloads | Allocates a physically deep-isolated storage space for a single ultra-high-throughput table |
| Online table mode conversion | Supports 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 met | Does not support online conversion to other table modes |
| AI Memory long-term memory support | Not 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 scenarios | Lightweight traditional CRUD prototypes or pure document-based legacy applications | Enterprise-grade agent applications, intelligent customer service middle platforms, and RAG + Memory integrated production projects | Special 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 type | Applicable caller | Core request headers | Permission determination mechanism | Subject to row-level/file-level ACL |
|---|---|---|---|---|
| Console Session (developer session) | Developer operating in a /console/ browser, or using the Console SDK | Cookie session + X-Appwrite-Mode: admin + X-Appwrite-Project | Determined 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 calls | X-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 switches | No (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 days | Yes (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:
External business identifier (
$id): The unique resource ID exposed externally (e.g., knowledge basekb_enterprise_support, synonym lexiconlex_enterprise_synonyms, AI gatewaygw_7194685489feb1e169548619). When creating a resource, you can pass a custom$id(letters, digits, hyphens, underscores, and periods allowed; must not start with a special character; up to 36 characters) or useunique()to have the server auto-generate a high-entropy unique ID.Internal physical sequence number (
$sequence/ Internal ID): An auto-increment sequence identifier used internally by OceanBase for clustered indexes, foreign key associations, and cursor pagination (cursorAfter/cursorBefore). Callers only operate on resources via$idand need not care about the underlying physical sequence.
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 dimension | Syntax format | Precise semantics and scope of application | Production configuration example (intelligent customer service support ticket scenario) |
|---|---|---|---|
| Actions | read("<role>") | Allows reading rows, downloading/previewing files, or viewing resource metadata | read("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 files | delete("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 Selectors | any | Any requester (including anonymous unauthenticated visitors and logged-in users) | Public knowledge base attachment bucket configuration read("any") |
guests | Only unauthenticated anonymous session visitors | Anonymous feedback table configuration create("guests") | |
users / users/verified | Any logged-in end user / only logged-in users who have completed email or phone verification | Enterprise 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:
LLM Gateway (model gateway
/llm-gateway): Manages model provider credentials (e.g., Alibaba Cloud Bailiandashscope-prod) and the model capability catalog (Chatqwen-plus/qwen-turbo, Embeddingtext-embedding-v31024 dimensions, Rerankqwen3.7-text-rerank, Visionqwen-vl-max), and issues Gateway Keys supporting monthly Token budgets and RPM/TPM rate limiting.AI Gateway (unified AI gateway
/ai-gateway): The governance plane for complex production traffic (e.g.,prod-enterprise-ai-gatewaygw_7194685489feb1e169548619), providing logical model routing (lm-enterprise-chatprimary/backup failover and weighted traffic splitting), input/output safety guardrails (gp-enterprise-safety), semantic caching (cp-semantic-cache), and MCP tool/agent registration governance.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).Memory & PowerContext (long-term memory and managed context
/memory·/powercontext): Within anShared V2project, 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 asdst_3e5b09f456c5d5c332507ec1dbe3eb6d). Supports four types of Pipeline with draft verification and publishing plus secondary manual confirmation.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.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 tier | Core operation modules | Console route path | Minimum required organization role |
|---|---|---|---|
| Account level (Account) | Personal profile, MFA and recovery codes, global sessions, pending-cleanup project recovery, table mode conversion history | /console/account | Any 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 domain | Platform-enforced default behavior | Practical impact on development and operations |
|---|---|---|
| Outbound network and SSRF protection | Rejects 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 sites | Functions 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 transmission | Passing Function API Keys via URL query string is strictly forbidden | Triggering 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-closed | Private storage buckets with image content moderation enabled adopt a fail-closed policy | Once 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 validation | Before activating a new schema version, consistency of the underlying OceanBase physical table structure is mandatorily validated | If 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 recovery | Non-transactional idempotent read requests support automatic reconnection recovery when connections drop; explicit transaction requests are never automatically replayed | When 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 credentials | OAuth2 Client Secrets, model provider API Keys, moderation AK/SK, and global Secret variables are write-only and never echoed back | After 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
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).In the member list table, verify each member's Name, Email, 2FA (two-step verification enablement status), and Roles (organization roles).
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
Developerto algorithm engineers,Editorto knowledge operations staff, andBillingto finance personnel).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
In the organization project list, click into
企业智能客服与知识中台(enterprise-ai-hub-210), and click Settings at the bottom of the left navigation bar.Under the Overview tab, find the Table Mode card:
Confirm that the current project runs in
Shared V2mode (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 typerelationship; after submitting the conversion, you can track the asynchronous conversion progress under the Account → Table mode conversions tab.
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:
Go to the left sidebar Databases → click database
enterprise_biz_db→ click data tablecustomer_tickets→ switch to the Settings tab.In the Permissions (table-level permissions) area:
Click Add role → select All users (
users), and check onlyCreate(allowing any logged-in end user to create ticket rows, but do not check the table-levelRead, 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 checkReadandUpdate(allowing customer support team members to read and process all tickets).
Enable Row security (row-level security toggle) and click Update to save.
When the client or server inserts a specific ticket row (e.g.,
TK-20261022-001, owned by customeruser_zhangwei_001), writeread("user:user_zhangwei_001")andupdate("user:user_zhangwei_001")into that row's permission array to achieve precise row-level tenant isolation.
Security Defaults
| Domain | Default behavior |
|---|---|
| External URLs | Reject local, private network, and cloud metadata addresses (SSRF protection) |
| Function / Site | Run under restricted identity; fail immediately when security conditions are not met, with no fallback to elevated execution |
| Console SQL | Do not display MySQL wire direct-connection information in the browser |
| Schema changes | Validate physical structure before activation; on failure, keep the currently live version serving |
| SQL Proxy transactions | No public transaction status; transaction control commands are rejected; unconfirmed write results should be read back first and handled according to the idempotency policy |
| Storage moderation | Private image moderation fails closed; on failure, uploads are cleaned up |
| Login state | Single-use, bound to project / browser / callback / Client ID / state revision |
| Test sessions | Sessions created by OAuth login testing are isolated from Console sessions; logging out of a test does not log out of the Console |
| Function API Key | No 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:
Backend requests carry
X-Appwrite-Key: standard_...(Server API Key). As long as the Key hasrows.read/databases.readscope, it can bypass table-level and row-level ACLs to read all data.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
readpermission at the table level, and the row itself also lacksread("user:{userId}")(or the row security togglerowSecurityis 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:
Column deletion switch (Column deletion): Since deleting a physical column irreversibly erases all historical business data in that column, the platform security policy mandates that only the organization Owner and platform administrators are authorized to enable this switch; regular
Admin,Developer, orEditorhave no permission to toggle it.Table mode conversion blocked: If the current project is in “deep exclusive table” mode, conversion is physically unsupported; if the project contains collections with
relationship(relation) attributes, pre-conversion validation will proactively block the process and prompt you to remove the relation collections first. Do not execute concurrent Schema changes while conversion is in progress.

