AgentbaseDocs
文档目录

Python 示例

Python Server SDK(agentbase 包,snake_case)与 Console SDK(agentbase_console 包)的初始化与各功能点调用写法。**坐标按 agentbase-sdks 当前发布面 v2.9.0(ZIP 制品 release 终态)**(2.6.0 迭代无可证可安装产物,缺口登记见 changelogs/2.6.0.md);运行要求 Python 3.9+,运行时依赖 requests 与 pydantic>=2,<3。

获取与安装(离线 wheel)

制品不发布到 PyPI;从 release ZIP 解压后 pip 安装(内网可用 PIP_INDEX_URL 指向私有镜像提供依赖):

BUNDLE_DIR="$(mktemp -d)"
BASE_URL="https://code.alipay.com/obai/agentbase-sdks/releases/download/v2.9.0"
curl -fsSL -o "$BUNDLE_DIR/agentbase-python-sdk-2.9.0.zip" "$BASE_URL/agentbase-python-sdk-2.9.0.zip"
curl -fsSL -o "$BUNDLE_DIR/agentbase-console-python-sdk-2.9.0.zip" "$BASE_URL/agentbase-console-python-sdk-2.9.0.zip"
curl -fsSL -o "$BUNDLE_DIR/SHA256SUMS" "$BASE_URL/SHA256SUMS"
(cd "$BUNDLE_DIR" && sha256sum -c --ignore-missing SHA256SUMS)
unzip "$BUNDLE_DIR/agentbase-python-sdk-2.9.0.zip" -d "$BUNDLE_DIR"
unzip "$BUNDLE_DIR/agentbase-console-python-sdk-2.9.0.zip" -d "$BUNDLE_DIR"
(cd "$BUNDLE_DIR/agentbase-python-sdk-2.9.0" && sha256sum -c SHA256SUMS)
(cd "$BUNDLE_DIR/agentbase-console-python-sdk-2.9.0" && sha256sum -c SHA256SUMS)

pip install "$BUNDLE_DIR/agentbase-python-sdk-2.9.0/agentbase_python_sdk-2.9.0-py3-none-any.whl"
pip install "$BUNDLE_DIR/agentbase-console-python-sdk-2.9.0/agentbase_console_python_sdk-2.9.0-py3-none-any.whl"

不要安装开源 appwrite 官方包冒充 Agentbase Python SDK——它缺少 TablesDB、Knowledge Bases 等 Agentbase 扩展 surface。

Server SDK 初始化

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

from agentbase.client import Client

client = (
    Client()
    .set_endpoint('https://appbuild.oceanbase.com/v1')   # 带 /v1;SIT 为 https://appbuild-sit.oceanbase.com/v1
    .set_project('<PROJECT_ID>')
    .set_key('<SERVER_API_KEY>')                          # 最小 scope 的项目 API Key,只存服务端
)

Client 其它配置(均链式返回 Client):set_organization(value)(组织级查询需要)、set_jwt(value) / set_session(value)(仅用于 endpoint 明确要求用户身份的受控流程,不是 API Key 的通用替代)、set_self_signed(status)(自签 TLS 环境)、add_header(key, value)。

Console SDK 初始化

Console 登录响应体不含 session secret(只在 a_session_console cookie),先经原始 HTTP 登录取 cookie,再挂到 Console SDK client:

import re

import requests
from agentbase_console.client import Client as ConsoleClient

resp = requests.post(
    'https://appbuild.oceanbase.com/v1/account/sessions/email',
    headers={'X-Appwrite-Project': 'console', 'Content-Type': 'application/json'},
    json={'email': CONSOLE_EMAIL, 'password': CONSOLE_PASSWORD},
)
secret = re.search(r'a_session_console=([^;]+)', resp.headers['set-cookie']).group(1)

console_client = (
    ConsoleClient()
    .set_endpoint('https://appbuild.oceanbase.com/v1')
    .set_project('console')
)
console_client.add_header('origin', 'https://appbuild.oceanbase.com')
console_client.add_header('x-forwarded-host', 'appbuild.oceanbase.com')
console_client.add_header('Cookie', f'a_session_console={secret}')

Console 服务面(agentbase_console.services)含 account、teams、projects、users、proxy、migrations 等;方法名与 Server 包同为 snake_case。Console 包与 Server 包可在同一环境共存。

TablesDB(建库、建表、行、查询)

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'), Query.limit(25)],
    total=False,
)

要点:columns / indexes 为 dict 列表(生成器校验为 DatabaseColumnDefinition / DatabaseIndexDefinition),列/索引 type 以功能点文档数据库为准;增量列接口返回多为 202 异步任务;update_rows / delete_rows 无 queries 时作用全表,务必加 Query 过滤。

DocumentsDB 与事务

DocumentsDB 是 TablesDB 的 document 语义面(create_collection / create_document / list_documents…):

from agentbase.services.documents_db import DocumentsDB

documents_db = DocumentsDB(client)

tx = documents_db.create_transaction(ttl=60)
documents_db.create_operations(
    transaction_id=tx['$id'],
    operations=[{
        'databaseId': 'app-db',
        'collectionId': 'tasks',
        'documentId': 'doc-1',
        'action': 'create',           # create/update/upsert/delete/increment/...
        'data': {'title': 'tx doc'},
    }],
)
documents_db.update_transaction(transaction_id=tx['$id'], commit=True)   # 或 rollback=True 回滚

用户、团队与存储

from agentbase.input_file import InputFile
from agentbase.services.storage import Storage
from agentbase.services.teams import Teams
from agentbase.services.users import Users

users = Users(client)
created = users.create(
    user_id=ID.unique(), email='user@example.com',
    password='<password>', name='Example User',
)
users.delete(user_id=created['$id'])

teams = Teams(client)
teams.create(team_id='my-team', name='My Team', roles=['owner'])

storage = Storage(client)
storage.create_bucket(bucket_id='attachments', name='附件', file_security=True, enabled=True)
storage.create_file(
    bucket_id='attachments', file_id=ID.unique(),
    file=InputFile.from_path('/path/to/report.pdf'),   # 或 InputFile.from_bytes(b'...', 'report.txt', 'text/plain')
)
data: bytes = storage.get_file_view(bucket_id='attachments', file_id='<file-id>')

service 方法同步返回 pydantic 模型:按字段名访问(user.id、created['$id'] 见上);model_type 参数只类型化 document / row 的业务 data payload。服务端创建用户 session 的返回体不含 secret(只在 a_session_<projectId> cookie 里);需要用户态 client 时读取该 cookie 后 Client().set_session(secret)。

Memory / Knowledge Bases / 网关与观测

专题能力(Memory、Knowledge Bases、LLM Gateway、AI Gateway、Observability、Moderation、Messaging、Sites 等)在 agentbase.services 下均有对应模块,构造统一为 Xxx(client);方法面与 Node SDK 同构(snake_case),Python 自 15.4.0 起补齐 Knowledge Bases 调用面。参数与返回结构见各功能点文档(记忆、知识库、模型与 AI 网关、可观测等);JavaScript 写法对照见 javascript.md 对应小节,逐字段的 Python 签名以 agentbase.services 模块源码为准。

错误处理

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,type 为服务端错误类型

事实源