agentbase-docs

Server SDK(Python)

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__ 为空,全部符号按模块导入:

from agentbase.client import Client

client = (
    Client()
    .set_endpoint('https://appbuild.oceanbase.com/v1')   # SIT: https://appbuild-sit.oceanbase.com/v1
    .set_project('<PROJECT_ID>')
    .set_key('<SERVER_API_KEY>')                          # 最小 scope 的项目 API Key
)

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

5 分钟上手

from agentbase.id import ID
from agentbase.query import Query
from agentbase.services.tables_db import TablesDB

tables_db = TablesDB(client)

tables_db.create(database_id='app-db', name='App')
tables_db.create_table(
    database_id='app-db', table_id='tasks', name='Tasks',
    row_security=True, enabled=True,
    columns=[{'key': 'title', 'type': 'string', 'size': 256, 'required': True}],
    indexes=[{'key': 'idx_title', 'type': 'unique', 'attributes': ['title']}],
)
tables_db.create_row(database_id='app-db', table_id='tasks', row_id=ID.unique(), data={'title': '写周报'})
rows = tables_db.list_rows(database_id='app-db', table_id='tasks',
                           queries=[Query.order_desc('$createdAt')], total=False)

调用约定

功能面导航

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

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

错误处理

from agentbase.exception import AgentbaseException

try:
    tables_db.get_row(database_id='app-db', table_id='tasks', row_id='missing')
except AgentbaseException as error:
    print(error.code, error.type)   # code 为 HTTP 状态码:404 / 429 / 401·403

示例指引

事实源