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

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. Model access and routing: Connect providers on the Models page and configure tool access in AI Gateway as needed.

  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, client platform registration and applicable browser origin checks, 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, AI GatewayModel provider access, gateway routing, and access managementConfigure available models and credentials
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.

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-prodCentrally 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 engineerProject actions depend on granted permissions and service switchesNo project API Key / Dev Key management permission by defaultRead-only member listDepends on deployment and authorization
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 specialistNo projects.read by default; this role alone cannot enter a project in self-hosted deploymentsNo management permission by defaultOrganization billing.read; availability depends on deploymentOrganization usage depends on authorization
AnalystData analyst / quality inspectorNo projects.read by default; this role alone cannot enter a project in self-hosted deploymentsNo management permission by defaultRead-only organization informationProject data depends on authorization

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. Query the public health endpoint of your environment (no API key is required). Set the AGENTBASE_ENDPOINT environment variable to your Agentbase service endpoint:

    curl -fsSL "$AGENTBASE_ENDPOINT/v1/health/version"

    A successful request returns HTTP 200 OK; version identifies the running version of that environment.

  2. Open that environment's console, sign in, and select your organization and project. Follow the prompts if additional verification is required.

  3. Use the sidebar to access the project overview, platforms, and API keys. A new project may show a getting-started guide first; the available content depends on the current page.

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 routingModels / AI Gateway/llm-gateway · /ai-gatewayAdd a model provider and configure gateway instances and tools as needed.
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 the required documents, and build GraphRAG, RAPTOR, and a Wiki as needed; 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

The table below lists selected capabilities described for version 2.10.0. Check the corresponding documentation and your target environment for current behavior, entry points, and availability:

Feature NameModuleCore Configuration Item or Interface IdentifierCapability Description
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 by the instance switch and email allowlist. Application code defaults _APP_SITES_ENABLED to enabled when unset, but deployments may override it; the Console entry also depends on the current user's allowlist status.

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