Docs
Contents

What is Agentbase

Agentbase is a one-stop backend and intelligent infrastructure platform for the engineering deployment of enterprise-grade AI-native applications and agents. Built on highly reliable application backend capabilities (authentication, relational and document databases, object storage, serverless cloud functions, messaging notifications, site hosting, and multimodal content moderation), the platform deeply integrates the LLM Gateway required by enterprise-grade agents, the unified AI Gateway, a rich-document hybrid retrieval knowledge base (Knowledge Base and domain Lexicon), long-term memory and skill self-evolution engine (Memory & Context Dreaming), the agent runtime workbench (Agent Runtime Workbench), and full-chain agent observability (AgentOps / Observability). This manual corresponds to Agentbase 2.10.0.

Agentbase project Console (Platform and Overview 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 deploying intelligent customer service, knowledge assistants, development Copilots, and automated business agents in enterprises, engineering teams typically face the pain point of a split between "application backend infrastructure" and the "AI-native tech stack": on one hand, they must assemble user authentication, business ticket databases, multi-tenant permissions, object storage, and asynchronous task queues themselves; on the other hand, they must independently maintain model routing gateways, RAG vector parsing pipelines, synonym/stopword intervention lexicons, long- and short-term session memory, and OpenTelemetry trace evaluation systems. The authentication systems, tenant isolation boundaries, and metering/billing standards of multiple systems cannot be aligned, resulting in long development cycles and difficult production troubleshooting.

Agentbase converges traditional BaaS (Backend-as-a-Service) and Agent Infra under a unified account → organization (Organization) → project (Project) governance model. Taking a typical production scenario, "enterprise intelligent customer service and knowledge platform" (project ID: enterprise-ai-hub-210, belonging to organization: Agentbase 企业智能中台 69c6d1aa00062e6bb60), as an example, the enterprise can achieve the following full-stack closed loop within a single Project space:

  1. Unified identity and business data hosting: manage customer service agent and end-customer identities via Auth; use the business database enterprise_biz_db based on the OceanBase Shared V2 model (such as the customer ticket table customer_tickets) and buckets kb_enterprise_docs and agent_multimedia_bucket to host high-concurrency reads and writes of structured documents and unstructured multimedia.

  2. Multi-model routing and enterprise-grade safety guardrails: connect the Tongyi Qianwen DashScope production provider through the model gateway (dashscope-prod, including qwen-plus, qwen-turbo, text-embedding-v3, qwen3.7-text-rerank, qwen-vl-max), and configure logical model routing lm-enterprise-chat, safety guardrails gp-enterprise-safety, and semantic caching policies cp-semantic-cache via the AI gateway prod-enterprise-ai-gateway (gw_7194685489feb1e169548619).

  3. Hybrid Retrieval RAG and Advanced Knowledge Compilation: In the knowledge base kb_enterprise_support, ingest architecture whitepapers, customer service SOPs, and troubleshooting manuals; bind a synonym lexicon lex_enterprise_synonyms and a stopword lexicon lex_support_stopwords; and enable GraphRAG knowledge graph, RAPTOR hierarchical clustering summaries, and LLM Wiki compilation pages as needed.

  4. Long-Term Memory Extraction and Skill Distillation: Based on the Shared V2 engine, extract cross-session factual memory and user profiles for end users (such as user_zhangwei_001 and user_lina_002), and asynchronously execute Context Dreaming context aggregation and Experience/Skill Distillation.

  5. Workbench Integration and Full-Chain Observability (AgentOps): In the agent workbench, bind the primary conversational model qwen-plus, the enterprise knowledge base, and the intervention lexicon with one click for streaming debugging, while tracking the Span waterfall, Token cost, parsing chunk quality, and knowledge index quality score of every request in the AgentOps hub.

Capability DomainCore ModulesCore Business Problems SolvedProduction-Grade Feature Highlights
Governance and FoundationAccount Center, organization management, project overview, limits and quotas, project settingsMulti-team development collaboration, multi-environment isolation, API credential authorization, and cost accountingThree-level UTC daily aggregated metering, 15 client platform origin verification, and independent read-only ban switches for project database/storage
Application Backend (Build)Auth, Databases, Storage, Functions, Sites, Messaging, ModerationEnd-to-end application user system, relational/JSON data persistence, file hosting, event-driven computing, and compliance risk controlOceanBase Shared V2 high-performance table mode, Schema version rollback, SQL Proxy, Java 17 prebuilt JAR deployment, and multimodal synchronous/asynchronous content moderation
Models and Gateway (AI)LLM Gateway (models), AI Gateway (unified AI gateway)Multi-vendor credential custody, primary-backup failover, semantic cache acceleration, prompt guardrails, and quota throttlingOne-click import of vendor catalogs such as DashScope, logical model routing, semantic cache hit analysis, and per-Key monthly Token budget control
Knowledge and Memory (AI)Knowledge Base, Lexicon, Memory, PowerContextChunking and ingesting complex documents, proper noun retrieval correction, multi-hop knowledge reasoning, cross-session personalized memory, and skill evolutionVector + full-text hybrid retrieval, hot synonym/stopword intervention, GraphRAG/RAPTOR/Wiki indexes, 4 types of publishable memory Pipelines, and image/PDF multimodal memory
Runtime and Operations (AgentOps)Agent workbench (Agent Runtime), agent operations (Observability)Rapid agent assembly verification, live conversation trace replay, low-score root cause diagnosis, and quantified RAG parsing and index quality evaluationProject-level workbench configuration persistence, native OpenTelemetry integration, and built-in GraphRAG/RAPTOR/Wiki index quality assessment templates with independent model review

Core Concepts and Architecture

Agentbase adopts a layered architecture with separation of the Console Plane and the Data Plane, and same-origin isolation of the traditional application backend and AI engines. All resources are strictly attached under the Account(账号) → Organization(组织) → Project(项目) three-level resource tree, with the project serving as the minimal complete boundary for data isolation, key authentication, service switches, table modes (JsonTable / Shared V2), and metering quotas.

What is Agentbase: 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

Core Architecture Components Table

Architecture LayerCore ConceptIdentifier and Example (Production Scenario)Architecture Responsibilities and Engineering Constraints
Organization Layer (Organization)Team and billing containerAgentbase 企业智能中台(69c6d1aa00062e6bb60)Hosts multiple projects and centrally manages team member roles (owner, admin, developer, editor, billing, analyst), 30 daily aggregated usage, and inactive project cleanup.
Project Layer (Project)Resource and security isolation boundary企业智能客服与知识中台(enterprise-ai-hub-210)Binds to a physical region and the underlying table storage mode (e.g., Shared V2); databases, storage buckets, knowledge bases, memory spaces, and API Keys are fully isolated between projects.
Model Routing LayerVendors and logical gatewaydashscope-prod / prod-enterprise-ai-gatewayCentrally consolidates external LLM API Keys (stored masked, never echoed back), and internally provides a standard invocation surface for knowledge base chunk vectorization, memory extraction, online inference, and LLM-as-a-Judge evaluation.
Knowledge and Memory LayerStructurally enhanced contextkb_enterprise_support / lex_enterprise_synonyms / MemoryCombines raw documents in storage buckets, vector indexes, lexicon synonym expansion, and user long-term factual memory to assemble high-recall, low-hallucination dynamic Prompt contexts for agents.
Observability and Evaluation LayerAgentOps closed-loop quality governanceTraces / Observations / EvaluationsAutomatically collects or receives agent execution traces via OTLP, providing quantified scoring and root cause analysis from chunk parsing quality and GraphRAG/Wiki index artifact quality to end-to-end response quality.

Roles, Entry Points, and Relationships

In daily development and operations, team members in different roles collaborate to deliver applications through different Console views. Understanding Console role permissions, service switches, and the boundary between the Console Plane and the Data Plane is a prerequisite for using Agentbase securely.

1. Organization Roles and Operation Permission Matrix

Organization RoleTypical PositionApplication Backend and AI Resource Write PermissionAPI Key / Credential ManagementOrganization Settings and Member GovernanceUsage and Observability Visibility
OwnerPlatform architect / technical leadFull read/write (including column deletion, table mode conversion, project deletion)Create, edit, view full Secrets, revokeCreate/delete organizations, invite/remove members, clean up inactive projectsFull three-level view of account, organization, and project
AdminDevelopment lead / operations leadFull read/write (excluding destructive switches restricted to Owner)Create, edit, view authorized Secrets, revokeModify organization settings and invite members (cannot delete organization)Full organization and project view
DeveloperBackend engineer / AI algorithm engineerRead/write databases, storage, functions, knowledge bases, memory, gateway, and evaluationsCreate and manage project API Keys / Dev KeysRead-only view of member listFull organization and project view
EditorKnowledge operations / Prompt engineerMaintain table data, knowledge base documents, lexicon entries, and evaluation datasetsUse within authorized scopeRead-only view of member listProject-level business and observability view
BillingFinance and procurement specialistRead-only (cannot modify business configuration or trigger builds)Cannot create or view SecretsManage bills, invoices, and subscription plansOrganization and project usage metering view
AnalystData analyst / quality inspectorRead-only (cannot modify business resources)Cannot create or view SecretsRead-only viewObservation traces, evaluation reports, and usage statistics

2. Product Capability Boundaries and Four Core Principles

Feature Details and Operation Guide

This section explains, from the perspective of an enterprise team newly onboarding, how to use the Console to verify the platform version, gain a global understanding of the project, and follow the standard evolution path from basic services to AI modules.

1. Verify the Instance Service Version and Console Entry Points

Before starting project configuration, it is recommended to first confirm the server version of the current environment and log in to the Console:

  1. Run the public health check endpoint in a terminal (no API Key required):

    curl -fsSL https://appbuild.oceanbase.com/v1/health/version

    The expected response is HTTP 200 OK with the JSON payload {"version":"2.10.0"}.

  2. Open the Console address https://appbuild.oceanbase.com/console/ in a browser, log in with the enterprise developer account and complete MFA secondary verification, switch to the target organization Agentbase 企业智能中台 (ID: 69c6d1aa00062e6bb60) in the top navigation bar, and click to enter project 企业智能客服与知识中台 (ID: enterprise-ai-hub-210).

  3. After entering the project, the Overview page is displayed by default (as shown in Figure 1); the top shows real-time connection count, request trends, database read/write throughput, and storage usage summaries; the Integrations area at the bottom centrally manages registered client platforms (Platforms), server production keys (API keys), and development/debug keys (Dev keys).

2. Console Left Sidebar Sections and the Standard Build Flow

The left navigation bar of the Agentbase project Console is divided into three core areas according to the development evolution lifecycle; teams are advised to build enterprise intelligent applications layer by layer in the following order:

Build StageSidebar Entry NameConsole Route SuffixKey Configuration Actions and Outputs (using enterprise-ai-hub-210 as an example)
Stage One: Project Foundation and Security BaselineOverview / Settings/overview · /settingsConfirm the project table mode is OceanBase Shared V2; enable services such as AI Gateway, Knowledge Bases, and Memory in Services; create a standard_ API Key following the least-privilege principle.
Phase Two: Application Backend Build (Build)Auth / Databases / Storage / Functions / Moderation/auth · /databases · /storage · /functions · /moderationConfigure end-user login methods; create the business database enterprise_biz_db and the ticket table customer_tickets (with entries such as ticket TK-20261022-001); create the storage bucket kb_enterprise_docs and upload policy documents; enable multimodal content moderation on the write path.
Phase Three: Model Gateway and Routing Governance (AI)Models / AI Gateway/llm-gateway · /ai-gatewayOn the Models page, add dashscope-prod from the preset catalog (importing qwen-plus, text-embedding-v3, qwen3.7-text-rerank, qwen-vl-max); on the AI Gateway page, create prod-enterprise-ai-gateway and bind the logical model lm-enterprise-chat, safety guardrail gp-enterprise-safety, and semantic cache cp-semantic-cache.
Phase Four: Knowledge Engineering and Long-Term Memory (AI)Knowledge Base / Lexicon / Memory / Context/knowledge-base · /memory · /powercontextCreate the synonym dictionary lex_enterprise_synonyms and the stopword dictionary lex_support_stopwords; create the knowledge base kb_enterprise_support, upload 4 core enterprise Markdown documents, and build GraphRAG, RAPTOR, and a compiled Wiki of 10 pages; initialize the Shared V2 Memory service, configuring the four types of Memory Pipelines and experience and skill distillation.
Phase Five: Agent Integration Testing and AgentOpsAgent Workbench / AgentOps / Trace logs/agent-runtime · /observability · /logsIn the Agent Workbench, bind qwen-plus and kb_enterprise_support for multi-turn conversation testing; in AgentOps, view the Trace waterfall and run knowledge base parsing evaluation and knowledge index quality evaluation tasks.

3. 2.10.0 Core Feature Panorama Checklist

To help architects upgrading from earlier versions or evaluating the platform for the first time quickly grasp the current baseline capabilities, the table below summarizes the key production capabilities of Agentbase 2.10.0 and the corresponding verification methods:

Feature NameModuleCore Configuration Item or Interface IdentifierConsole Verification Result
Standalone Knowledge Index Quality EvaluationAgentOps → EvaluationBuilt-in templates: GraphRAG / LLM Wiki / RAPTOR Index Quality; by default, 30 items are sampled per capability layerto generate 0~1 capability-level quality scores; after independent model review, supports drilling down by kind=index to view per-item rule and model scoring details
Document Hierarchy Tags and Sub-Product FilteringKnowledge Base → Documents / Retrieval TestingdocumentTag ({subProductId}_{sectionCode}_{fileKey}) and a standalone subProductId fieldThe document list supports tag tree/flat view switching, and single-library and cross-library retrieval support precisely narrowing the retrieval scope by subProductId and metadataFilter
Intervention Lexicon Closed LoopKnowledge Base → LexiconSynonym dictionary (bidirectional equivalence/unidirectional expansion) and stopword dictionaryOnce bound to a knowledge base or the Agent Workbench, hybrid retrieval automatically performs business jargon expansion and removal of high-frequency noise words
Four Types of Memory Pipelines and Skill Secondary ConfirmationMemory → Configuration / Experience & SkillsFour types of Pipelines: Memory, Profile, Experience & Skills, and Forgetting; evolution.requireConfirmationsupports Pipeline draft saving, real-sample validation, publishing, and rollback; skill distillation supports candidate version Diff comparison, manual editing, and approval/rollback
Java 17 Prebuilt JAR Function DeploymentFunctions → DeploymentRuntime java-17.0 + artifactMode=java-jar (manifest declares Main-Class)No need to upload a source archive for recompilation; upload a prebuilt JAR within the valid size limit (default 100 MB, also subject to plan limits); wait for the deployment to become ready, then confirm activation and execution results
Project Database and Storage Standalone Read-Only FenceLimits and Quotas (Platform Governance)databaseReadOnly / storageReadOnlyWhile enabled, writes to the corresponding domain are rejected (returning project_database_read_only or project_storage_read_only), guaranteeing zero dirty writes during migration and fault isolation periods

2.10.0 Notable Capabilities

FAQ and Troubleshooting

Q1: Why can't I see "AI Gateway", "Messaging", or "Sites" entries in the Console's left navigation bar?

Cause and troubleshooting steps:

  1. AI Gateway: The project-level service switch is disabled by default. Have a member with project write permission (owner / admin / developer / editor) go to Settings → Overview → Services, find AI Gateway (Unified AI Gateway), and toggle it to enabled; after refreshing, the AI Gateway entry will appear in the sidebar.

  2. Messaging: In the current version, this navigation item is hidden from the sidebar by default, but the underlying service is fully available. You can access it directly in the browser via /console/project-{region}-{project}/messaging (for example /console/project-default-enterprise-ai-hub-210/messaging), or jump straight to it using the shortcut command center at the top of the Console.

  3. Sites: Controlled jointly by the instance-level deployment environment variable _APP_SITES_ENABLED and an email whitelist. If the variable is not enabled on the current private or pre-production instance, the sidebar automatically hides the Sites entry.

Q2: Why does calling a knowledge base advanced index or Memory interface return HTTP 412 Precondition Failed?

Cause and troubleshooting steps: In Agentbase, HTTP 412 explicitly means a Prerequisite or deployment-level Capability is not satisfied, rather than an ordinary parameter error (400) or insufficient permission (401/403). Common triggering scenarios include:

Q3: Why does a server-side script calling an API with an API Key return 401 general_unauthorized_scope?

Cause and troubleshooting steps: Agentbase project API Keys strictly follow the Least Privilege principle. If, when creating an API Key, you do not check the Scope the target interface belongs to (for example, calling user queries without checking users.read, or calling knowledge base retrieval without checking the knowledge-base-related Scope), the server will intercept the request directly and return general_unauthorized_scope. Go to the project's Overview → Integrations → API keys, open the corresponding Key's detail page, complete the required permissions in the Scopes collapsible panel, and save; it takes effect immediately without changing the Key Secret.

Q4: After turning off a Service switch in project settings, will existing data be wiped? Can backend services still access it?

Cause and troubleshooting steps: No data is deleted, and server-side API Key access is unaffected. The switches in the project's Settings → Services only control the reachability of the client access surface (Client SDK / direct access from browsers and mobile clients carrying a user Session). After a service is turned off, direct requests from frontend applications are rejected, but calls initiated by backend microservices carrying a valid Server API Key still execute normally, and the underlying database tables, storage bucket files, and knowledge base indexes remain fully preserved.

For easy reference to all site features, the following is a direct index of all chapters in this manual (zh-CN):