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.

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.

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:

Console nameTable modeDescription
Shared tablejsonTableUses JSON table mode; availability and project quotas depend on instance configuration.
Dedicated tableshared / Shared V2Uses Shared V2, which is required by this version's Memory route.
Deep dedicated tablecollectionProject metadata tables are also dedicated; this is not a setting for one business table.

Project table-mode conversion currently covers jsonTable and Shared V2 and requires the actual preflight conditions to pass; collection is outside those two directions. Availability of historical sharedV1 depends on instance configuration. Check the available options and restrictions in your environment before choosing or converting.

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)Web, mobile, and other end-user clientsX-Appwrite-Project + Session Cookie or X-Appwrite-JWTBrowser Origin is checked when applicable; service switches, identity, and resource permissions also apply. Mobile package registration does not imply package validation on every requestYes (resource permissions control data access)
Dev Key (development/debugging key)Local development and debuggingX-Appwrite-Project + X-Appwrite-Dev-Key: <DEV_KEY>Can bypass rate limits and applicable browser origin checks. The Console offers 1, 7, or 30 days; the management API does not enforce a 30-day maximum. Set an expiration and revoke when finished.Yes (does not elevate data access permissions; client identity permissions still apply)

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 (/ai-gateway): Manages gateway instances, policies, and tool access.

  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, keys, service switches, and project resources/console/project-{region}-{project}/*Project entry requires projects.read; platform and key writes require platforms.write, keys.write, or devKeys.write respectively, held by owner / admin by default

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 provides security controls whose coverage and configuration depend on the entry point and deployment:

Security domainPlatform-enforced default behaviorPractical impact on development and operations
Outbound network and SSRF protectionSome protected outbound requests validate targets by default, restricting loopback, private, link-local, and cloud metadata addresses; deployment configuration can affect this protectionEntry points use different policies, and AI Gateway has separate private-network settings. Verify Function and Site build/runtime egress against the execution environment and network policy; do not assume a single guard covers all outbound requests.
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 policyImage violations, size-limit breaches, or moderation errors fail the upload; deletion is attempted when the cleanup step is reached, and its outcome must be checked.
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 masks. Project API key list and detail plaintext visibility depends on project identity and active organization membership; requests made with an API Key are redacted.

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 your organization in the top organization switcher and click Members in the top tab bar to open /console/organization-{organizationId}/members.

  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).

    • Before converting table mode, check available target pools and preflight results. Memory data or PowerContext configuration blocks conversion; assess retention and migration needs first. After submission, track the asynchronous task under Account → Table mode conversions.

  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 URLsSome entry points restrict local, private, and metadata addresses by default; coverage and exceptions depend on deployment configuration
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 moderationImage moderation failures fail the request; verify whether cleanup was reached and succeeded
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: The organization billing and analyst roles do not include projects.read by default, so those roles alone cannot enter a project in the self-hosted configuration. Organization billing and usage capabilities depend on the deployment and granted permissions. Project resource actions require their respective permissions. Creating API keys, dev keys, or registering platforms requires the corresponding management permission, held by organization owner or admin by default; ask an administrator to act according to the actual responsibility.

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

Cause and troubleshooting steps: