Docs
文档目录

Server SDK(Python)

运行示例前,请将 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 等占位符按实际使用位置替换为目标环境信息,并核对项目及凭据属于同一环境。

Python 后端 / 管理脚本 / 数据管道以项目 API Key 调用 Server SDK(agentbase 包,snake_case)。API Key 请求跳过行级权限检查(hasRole),只存受控服务端。Node / Java / Go 面见同目录 nodejs.md / java.md / go.md。

制品与安装

要求 Python 3.9+,运行时依赖 requests 与 pydantic>=2,<3。制品未发布到 PyPI:从 agentbase-sdks release ZIP 解压后 pip 安装 wheel(含 Console 包),完整命令见 ../integration.md「Python 说明」与 ../examples/python.md「获取与安装」。不要安装开源 appwrite 包冒充(缺 TablesDB / Knowledge Bases 等 surface)。

初始化

agentbase 包的 __init__ 为空,全部符号按模块导入:

Python Server SDK 2.12.0 的默认请求可能在跨主机跳转时转发项目 API Key。本页使用直接 HTTP 请求关闭自动跳转,适用于已确认的服务端 API 地址。

import os

import requests

endpoint = os.environ['APPBASE_ENDPOINT'].rstrip('/')
response = requests.get(
    endpoint + '/tablesdb',
    headers={
        'X-Appwrite-Project': os.environ['APPBASE_PROJECT_ID'],
        'X-Appwrite-Key': os.environ['APPBASE_API_KEY'],
    },
    allow_redirects=False,
    timeout=10,
)
if not 200 <= response.status_code < 300:
    raise RuntimeError(f'Agentbase request failed: HTTP {response.status_code}')
databases = response.json()

其它配置(均链式返回 Client):set_organization(value)(组织级查询)、set_jwt(value) / set_session(value)(仅限 endpoint 明确要求用户身份的受控流程)、set_self_signed(status)、add_header(key, value)。

5 分钟上手

建库、建表、写行和查询请参阅数据库接口。逐步检查响应状态,建表后再写入数据。

调用约定

客户端配置、游标分页与文件上传实战

agentbase.client.Client 提供完整的链式配置方法,支持自定义超时、TLS 校验、国际化语言与自定义请求头:

Client 方法注入的 HTTP 请求头适用场景与安全约束
set_endpoint(endpoint)—(请求基准地址)必填,形如 https://appbuild-sit.oceanbase.com/v1 或 https://appbuild.oceanbase.com/v1。
set_project(value)X-Appwrite-Project必填,目标项目 ID(如演示项目 enterprise-ai-hub-210)。
set_key(value)X-Appwrite-Key服务端主用鉴权方式,跳过 RLS(hasRole),按最小 scope 授权。
set_jwt(value)X-Appwrite-JWT代表特定登录用户调用数据面接口(受该用户 RLS 行级权限约束)。
set_session(value)X-Appwrite-Session服务端转发浏览器登录会话 Cookie 时装载。
set_organization(value)X-Appwrite-Organization组织级查询与治理接口指定组织上下文(如 69c6d1aa00062e6bb60)。
set_locale(value)X-Appwrite-Locale指定国际化返回语种(如 zh-CN)。
set_self_signed(status)—(TLS 校验开关)仅用于自签名证书的私有测试实例,生产环境保持 False。
add_header(key, value)自定义请求头注入分布式追踪头(traceparent)或自定义幂等标识。

游标分页、文件上传与异步任务轮询模板

分页时使用最后一条结果的 ID 作为游标,异步任务应设定截止时间并检查终态。文件上传与摄取分别见存储接口和文档摄取。定位参数示例:subProductId = finance。

与 Console SDK(agentbase_console)并用

Python 交付包 ZIP 中同时提供服务端数据面 wheel(agentbase)与管理面 wheel(agentbase_console)。在同一个 Python 进程中可同时导入两者(命名空间完全隔离):用 agentbase_console 执行组织/项目创建与 API Key 签发,再用 agentbase 执行业务表、存储、知识库与记忆数据面读写(详见 ../console-sdk/python.md)。

功能面导航

服务面与 Node 面同构(snake_case),全量映射见 nodejs.md「功能面导航」;各功能页:数据库、存储、函数、站点、用户、团队、消息、记忆、知识库(15.4.0 起补齐调用面)、LLM Gateway、AI Gateway、可观测、审核、横切服务。

无 Sql 服务(SQL 走 HTTP 形态或 Console SDK,../databases/sql-proxy.md);无 Realtime(客户端能力)。

错误处理

HTTP 接口返回错误时,用状态码和响应中的 type 判断原因。遇到跳转,应先核对配置的服务端地址。

示例指引