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 分钟上手
建库、建表、写行和查询请参阅数据库接口。逐步检查响应状态,建表后再写入数据。
调用约定
方法同步返回 pydantic 模型:按字段名访问(
user.id、listed.total);model_type参数只类型化 document / row 的业务datapayload(默认 dict)。columns/indexes为 dict 列表;增量列接口返回多为 202 异步任务。update_rows/delete_rows无 queries 时作用全表,务必加Query过滤。查询用
agentbase.query.Query(与 Node 同构)、ID 用agentbase.id.ID;权限可用Permission.read(Role.any())或直接传语法字符串 list。
客户端配置、游标分页与文件上传实战
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 判断原因。遇到跳转,应先核对配置的服务端地址。
示例指引
Python(Server / Console)完整调用写法:../examples/python.md