什么是 Agentbase
Agentbase 是面向企业级 AI 原生应用与智能体(Agent)工程化落地的一站式后端与智能基础设施平台。平台以高可靠的应用后端能力(身份认证、关系与文档数据库、对象存储、Serverless 云函数、消息通知、站点托管与多模态内容安全审核)为底座,深度融合企业级 Agent 所需的大模型网关(LLM Gateway)、统一 AI 网关(AI Gateway)、富文档混合检索知识库(Knowledge Base 与领域词库 Lexicon)、长期记忆与技能自进化引擎(Memory & Context Dreaming)、智能体运行工作台(Agent Runtime Workbench)以及全链路智能体可观测性(AgentOps / Observability)。
功能概述
在企业落地智能客服、知识助手、研发 Copilot 与自动化业务代理的过程中,工程团队通常面临“应用后端设施”与“AI 原生技术栈”割裂的痛点:一方面需要自行拼装用户鉴权、业务工单库、多租户权限、对象存储与异步任务队列;另一方面又需要独立维护模型路由网关、RAG 向量解析管线、同义词/停用词干预词典、长短期会话记忆以及 OpenTelemetry 轨迹评估系统。多套系统的鉴权体系、租户隔离边界与计量计费口径无法对齐,导致研发周期漫长、线上排障困难。
Agentbase 将传统 BaaS(Backend-as-a-Service)与 Agent Infra(智能体基础设施)收敛于统一的账号 → 组织(Organization) → 项目(Project)治理模型之下。以典型生产场景“企业智能客服与知识中台”(项目 ID:enterprise-ai-hub-210,归属组织:Agentbase 企业智能中台 69c6d1aa00062e6bb60)为例,企业只需在单个 Project 空间内即可完成以下全栈闭环:
统一身份与业务数据承载:通过 Auth 管理客服坐席与终端客户身份,使用基于 OceanBase
Shared V2模式的业务数据库enterprise_biz_db(如客户工单表customer_tickets)和存储桶kb_enterprise_docs、agent_multimedia_bucket承载结构化单据与非结构化多媒体的高并发读写。模型接入与路由:在模型页面接入供应商,并按需在 AI 网关配置工具接入。
混合检索 RAG 与高阶知识编译:在知识库
kb_enterprise_support中摄取架构白皮书、客服 SOP 与排障手册,绑定同义词词典lex_enterprise_synonyms与停用词词典lex_support_stopwords,按需开启 GraphRAG 知识图谱、RAPTOR 层次聚类摘要与 LLM Wiki 编译页面。长期记忆提取与技能蒸馏:基于
Shared V2引擎为终端用户(如user_zhangwei_001、user_lina_002)提取跨会话事实记忆与用户画像,并异步执行 Context Dreaming 上下文聚合及经验技能蒸馏(Experience/Skill Distillation)。工作台联调与全链路可观测(AgentOps):在智能体工作台一键绑定主对话模型
qwen-plus、企业知识库与干预词库进行流式调试,同时在 AgentOps 中心追踪每一笔请求的 Span 瀑布流、Token 成本、解析分块质量与知识索引质量评分。
| 能力域 | 核心模块 | 解决的核心业务问题 | 生产级特性亮点 |
|---|---|---|---|
| 治理与底座 | 账号中心、组织管理、项目总览、限额与配额、项目设置 | 多团队研发协同、多环境隔离、API 凭据授权与成本核算 | 三级 UTC 日聚合计量、客户端平台登记与适用的浏览器来源检查、项目数据库/存储独立只读封禁开关 |
| 应用后端(Build) | Auth 认证、Databases 数据库、Storage 存储、Functions 函数、Sites 站点、Messaging 消息、Moderation 内容审核 | 应用端到端用户体系、关系/JSON 数据持久化、文件托管、事件驱动计算与合规风控 | OceanBase Shared V2 高性能表模式、Schema 版本回滚、SQL Proxy、Java 17 预构建 JAR 部署、多模态同步/异步内容审核 |
| 模型与网关(AI) | LLM Gateway、AI Gateway | 模型供应商接入、网关路由与访问管理 | 配置可用模型和凭证 |
| 知识与记忆(AI) | Knowledge Base(知识库)、词库(Lexicon)、Memory(记忆)、上下文(PowerContext) | 复杂文档切片入库、专有名词召回纠偏、多跳知识推理、跨会话个性化记忆与技能进化 | 向量+全文混合检索、同义词/停用词热干预、GraphRAG/RAPTOR/Wiki 索引、4 类可发布记忆 Pipeline、图像/PDF 多模态记忆 |
| 运行与运维(AgentOps) | 智能体工作台(Agent Runtime)、智能体运维(Observability) | 智能体快速装配验证、线上对话轨迹回放、低分根因诊断、RAG 解析与索引质量量化评测 | 项目级工作台配置持久化、OpenTelemetry 原生接入、内置 GraphRAG/RAPTOR/Wiki 索引质量评估模板与独立模型复核 |
核心概念与架构
Agentbase 采用控制面(Console Plane)与数据面(Data Plane)分离、传统应用后端与 AI 引擎同源隔离的分层架构。所有资源严格挂载于 Account(账号) → Organization(组织) → Project(项目) 三级资源树下,以 Project 作为数据隔离、密钥鉴权、服务开关、表模式(JsonTable / Shared V2)与计量配额的最小完备边界。
核心架构组件表
| 架构层次 | 核心概念 | 标识与示例(生产实景) | 架构职责与工程约束 |
|---|---|---|---|
| 组织层(Organization) | 团队与计费容器 | Agentbase 企业智能中台(69c6d1aa00062e6bb60) | 承载多个 Project,统一管理团队成员角色(owner、admin、developer、editor、billing、analyst)、30 日聚合用量与不活跃项目清理。 |
| 项目层(Project) | 资源与安全隔离边界 | 企业智能客服与知识中台(enterprise-ai-hub-210) | 绑定物理区域(Region)与底层表存储模式(如 Shared V2);项目间数据库、存储桶、知识库、记忆空间与 API Key 完全隔离。 |
| 模型路由层 | 供应商与逻辑网关 | dashscope-prod | 统一收口外部大模型 API Key(掩码保存、不回显),对内为知识库切片向量化、记忆抽取、在线推理与 LLM-as-a-Judge 评估提供标准调用面。 |
| 知识与记忆层 | 结构化增强上下文 | kb_enterprise_support / lex_enterprise_synonyms / Memory | 结合存储桶原始文档、向量索引、词库同义词扩展与用户长期事实记忆,为智能体组装高召回率、低幻觉的动态 Prompt 上下文。 |
| 可观测与评测层 | AgentOps 闭环质量治理 | Traces / Observations / Evaluations | 自动采集或通过 OTLP 接收智能体执行轨迹,提供从分块解析质量、GraphRAG/Wiki 索引产物质量到端到端回复质量的量化评分与根因分析。 |
角色、入口与关联关系
在日常研发与运维中,不同岗位的团队成员通过 Console 的不同视图协作完成应用交付。理解 Console 角色权限、服务开关以及控制面与数据面的边界,是安全使用 Agentbase 的前提。
1. 组织角色与操作权限矩阵
| 组织角色 | 适用岗位 | 应用后端与 AI 资源写权限 | API Key / 凭据管理 | 组织设置与成员治理 | 用量与可观测性查看 |
|---|---|---|---|---|---|
| Owner | 平台架构师 / 技术负责人 | 全部读写(含列删除、表模式转换、项目删除) | 创建、编辑、查看完整 Secret、吊销 | 创建/删除组织、邀请/移除成员、清理不活跃项目 | 账号、组织、项目三级全量视图 |
| Admin | 研发主管 / 运维负责人 | 全部读写(不含仅限 Owner 的破坏性开关) | 创建、编辑、查看授权 Secret、吊销 | 修改组织设置、邀请成员(不可删除组织) | 组织与项目全量视图 |
| Developer | 后端工程师 / AI 算法工程师 | 项目操作按实际授权与服务开关执行 | 默认不具备项目 API Key / Dev Key 管理权限 | 只读查看成员列表 | 按实际部署及授权查看 |
| Editor | 知识运营 / Prompt 工程师 | 维护表数据、知识库文档、词库词条、评测数据集 | 按授权范围使用 | 只读查看成员列表 | 项目级业务与观测视图 |
| Billing | 财务与采购专员 | 默认无 projects.read,自托管时不能仅凭此角色进入项目 | 默认无管理权限 | 组织级 billing.read;功能取决于部署 | 组织用量以实际授权为准 |
| Analyst | 数据分析师 / 质检员 | 默认无 projects.read,自托管时不能仅凭此角色进入项目 | 默认无管理权限 | 只读查看组织信息 | 项目数据以实际授权为准 |
2. 产品能力边界与四条核心准则
准则一:部署级能力(Capability)与项目开关分层生效。知识库高阶索引、统一 AI 网关、站点托管(
_APP_SITES_ENABLED)与长期记忆受部署配置和相关组件影响。功能不可用时的 HTTP 状态与错误类型因接口和原因而异,应结合实际响应排查;版本升级不会自动更改所有部署开关。准则二:控制台可见性(Console 路由)不等于数据面已就绪。左侧边栏展示某个模块入口仅代表 Console 前端路由与角色权限放行;实际业务请求能否成功,取决于项目 设置 → 服务 开关、资源自身的
enabled/active状态、绑定的模型 Provider 连通性以及存储模式(如 Memory 强依赖项目处于Shared V2表模式)。准则三:开发者身份(Console Account)与终端用户身份(Project Auth User)严格物理隔离。登录
/console/login的账号用于管理组织与项目基础设施;项目 认证 模块下的用户(如user_zhangwei_001)是企业业务系统的终端客户或客服人员。两套会话 Cookie、JWT 与权限选择器彼此独立,严禁混用。准则四:协议版本与 SDK 响应格式精确协商。目标实例的运行版本可通过公开免鉴权接口
GET /v1/health/version实时核验(返回的version以目标环境实际结果为准)。Agentbase 官方自研 SDK(如agentbase-node-sdk@2.12.0、agentbase-web-sdk@2.12.0、agentbase-console-sdk@2.12.0)通过请求头X-AppBase-SDK: true与X-Appwrite-Response-Format: 2.12.0协商 2.12.0 完整响应结构;原生 Appwrite 兼容客户端则受独立版本上限(默认1.9.0)保护。
功能详解与操作指南
本节以企业新接入团队的视角,说明如何通过 Console 完成平台版本核验、项目全局认知及从基础服务到 AI 模块的标准演进路径。
1. 核验实例服务版本与控制台入口
在开始项目配置前,建议先确认当前环境的服务端版本并登录控制台:
在终端查询目标环境的公开健康接口(无需 API Key)。先将
AGENTBASE_ENDPOINT环境变量设为你的 Agentbase 服务地址:curl -fsSL "$AGENTBASE_ENDPOINT/v1/health/version"成功时返回 HTTP
200 OK,其中version为该环境的运行版本。打开该环境的控制台,登录后选择你的组织和项目。若环境要求额外验证,请按页面提示完成。
进入项目后,通过侧栏访问项目总览、平台和 API 密钥等页面。新项目可能先显示接入引导,具体内容以当前页面为准。
2. 控制台左侧边栏分区与标准构建流
Agentbase 项目控制台左侧导航栏按照研发演进生命周期划分为三大核心区域,推荐团队遵循以下顺序逐层构建企业智能应用:
| 构建阶段 | 侧边栏入口名 | 控制台路由后缀 | 关键配置动作与产出物(以 enterprise-ai-hub-210 为例) |
|---|---|---|---|
| 第一阶段:项目底座与安全基线 | 概览 / 设置 | /overview · /settings | 确认项目表模式为 OceanBase Shared V2;在 服务 中开启 AI Gateway、Knowledge Bases、Memory 等服务;创建最小权限原则的 standard_ API Key。 |
| 第二阶段:应用后端构建(Build) | 认证 / 数据库 / 存储 / 函数 / 内容审核 | /auth · /databases · /storage · /functions · /moderation | 配置终端用户登录方式;创建业务库 enterprise_biz_db 与工单表 customer_tickets(录入 TK-20261022-001 等工单);创建存储桶 kb_enterprise_docs 上传制度文档;开启写路径多模态内容审核。 |
| 第三阶段:模型网关与路由治理 | 模型 / AI 网关 | /llm-gateway · /ai-gateway | 添加模型供应商,按需配置网关实例和工具。 |
| 第四阶段:知识工程与长期记忆(AI) | 知识库 / 词库 / 记忆 / 上下文 | /knowledge-base · /memory · /powercontext | 创建同义词库 lex_enterprise_synonyms 与停用词库 lex_support_stopwords;创建知识库 kb_enterprise_support,上传所需文档,并按需构建 GraphRAG、RAPTOR 与 Wiki;初始化 Shared V2 记忆服务,配置四类记忆 Pipeline 与经验技能蒸馏。 |
| 第五阶段:智能体联调与 AgentOps | 智能体工作台 / 智能体运维 / 链路日志 | /agent-runtime · /observability · /logs | 在 智能体工作台 绑定 qwen-plus 与 kb_enterprise_support 进行多轮对话实测;在 智能体运维(AgentOps) 中查看 Trace 瀑布流,运行知识库解析评估与知识索引质量评估任务。 |
3. 2.10.0 核心特性全景核对表
下表列出 2.10.0 版本介绍过的部分能力,具体功能、入口和可用性请结合目标环境与对应章节核对:
| 特性名称 | 所属模块 | 核心配置项或接口标识 | 功能说明 |
|---|---|---|---|
| 知识索引质量独立评估 | 智能体运维 → 评估 | Built-in 模板:GraphRAG / LLM Wiki / RAPTOR Index Quality;默认每能力分层抽样 30 条 | 生成 0~1 能力级质量分,经独立模型复核后支持按 kind=index 下钻查看单条产物规则与模型评分明细 |
| 文档层级标签与子产品过滤 | 知识库 → 文档 / 检索测试 | documentTag({subProductId}_{sectionCode}_{fileKey})与独立 subProductId 字段 | 文档列表支持标签树/平铺切换,单库与跨库检索支持按 subProductId 与 metadataFilter 精准收窄召回范围 |
| 干预词库(Lexicon)闭环 | 知识库 → 词库 | 同义词词典(双向等价/单向扩展)与停用词词典 | 绑定至知识库或智能体工作台后,混合检索自动完成业务黑话扩展与高频噪音词剔除 |
| Memory 四类 Pipeline 与技能二次确认 | 记忆 → 配置 / 经验与技能 | 记忆、画像、经验与技能、遗忘四类 Pipeline;evolution.requireConfirmation | 支持 Pipeline 草稿保存、真实样例验证、发布与回滚;技能蒸馏支持候选版本 Diff 对比、人工编辑与批准回滚 |
| Java 17 预构建 JAR 函数部署 | 函数 → 部署 | Runtime java-17.0 + artifactMode=java-jar(manifest 声明 Main-Class) | 无需上传源码压缩包重新编译,上传符合有效大小上限的预构建 JAR(默认 100 MB,另受套餐上限约束);等待部署 ready 后确认激活和执行结果 |
| 项目数据库与存储独立只读栅栏 | 限额与配额(平台治理) | databaseReadOnly / storageReadOnly | 开启期间拒绝对应域写入(返回 project_database_read_only 或 project_storage_read_only),保障迁移与故障隔离期数据零脏写 |
2.10.0 值得关注的能力
知识库定位与筛选:文档可使用
documentTag和subProductId做精确定位;单库 / 跨库检索、文档列表和 Graph / Wiki 冲突列表支持按标签或子产品过滤。层级标签仍用于目录整理,两者用途不同。见文档与摄取和检索测试。知识索引质量评估:Observability 可分别评估 GraphRAG、RAPTOR 和 LLM Wiki 的索引产物;评估前须已有相应索引结果。见评估与评分。
版本化知识库:可基于 READY 版本创建工作副本,封存后发布,并保留受限的回滚目标。见版本管理。
常见问题与排障
Q1:为什么在控制台左侧导航栏看不到“AI 网关(AI Gateway)”、“消息(Messaging)”或“站点(Sites)”入口?
原因与排查步骤:
AI 网关(AI Gateway):项目级服务开关默认关闭。请具备项目写权限(
owner/admin/developer/editor)的成员前往 设置 → 概览 → 服务,找到 AI Gateway(统一 AI 网关) 并将其切换为开启状态,刷新后侧边栏即会显示 AI 网关 入口。消息(Messaging):当前版本侧栏默认隐藏该导航项,但底层服务完整可用。可通过浏览器直接访问
/console/project-{region}-{project}/messaging(例如/console/project-default-enterprise-ai-hub-210/messaging)或使用控制台顶部快捷键命令中心直接跳转。站点(Sites):受实例开关与邮箱白名单共同控制。应用代码未设置
_APP_SITES_ENABLED时默认为enabled,实际部署可能覆盖;Console 入口还取决于当前用户的白名单状态。
Q2:调用知识库高阶索引或 Memory 接口时返回 HTTP 412 Precondition Failed 是什么原因?
原因与排查步骤: HTTP 412 在 Agentbase 中明确代表前置条件或部署级能力(Capability)未满足,而非普通的参数错误(400)或权限不足(401/403)。常见触发场景包括:
项目表模式不匹配:例如尝试在传统
JsonTable模式的项目中初始化 Memory 记忆服务(Memory 强制要求项目采用 OceanBaseShared V2表模式)。请检查项目 设置 → 概览 → 项目表模式。未绑定必需的模型路由:例如开启知识库 GraphRAG/Wiki 构建或触发记忆异步提取前,尚未在 模型(LLM Gateway) 中配置可用的 Chat 与 Embedding 模型。
实例未部署对应可选组件:联系平台基础设施管理员核对对应 Worker 队列与索引服务是否已启用。
Q3:为什么服务端脚本使用 API Key 调用接口返回 401 general_unauthorized_scope?
原因与排查步骤: Agentbase 的项目 API Key 严格遵循最小权限(Least Privilege)原则。创建 API Key 时若未勾选目标接口所属的 Scope(例如调用用户查询未勾选 users.read,或调用知识库检索未勾选知识库相关 Scope),服务端将直接拦截并返回 general_unauthorized_scope。请进入项目 概览 → 集成 → API 密钥,点开对应 Key 详情页,在 Scopes 折叠面板中补齐所需权限后保存,无需更换 Key Secret 即可立即生效。
Q4:项目设置中关闭某个 Service 开关后,已有的数据会被清空吗?后台服务端还能访问吗?
原因与排查步骤: 不会删除任何数据,且不影响服务端 API Key 访问。项目 设置 → 服务 中的开关仅控制客户端访问面(Client SDK / 浏览器与移动端直接携带用户 Session 访问)的可达性。关闭某项服务后,来自前端应用的直接请求会被拒绝,但后端微服务携带有效 Server API Key 发起的调用依然正常执行,底层数据库表、存储桶文件与知识库索引完好保留。
相关文档
为方便查阅全站功能点,以下列出本手册(zh-CN)全部章节的直达索引:
导论与全局参考
账号、组织与项目治理
身份认证与用户管理(Auth)
数据库与数据治理(Databases)
应用后端服务(Storage / Functions / Sites / Messaging / Moderation)
模型网关与统一 AI 网关(Models & AI Gateway)
知识库与词库工程(Knowledge Base & Lexicon)
长期记忆与上下文工程(Memory & Context)
智能体工作台(Agent Runtime)
智能体可观测性与评估(AgentOps / Observability)