Python 示例
示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。
Python Server SDK(agentbase 包,snake_case)与 Console SDK(agentbase_console 包)的初始化与各功能点调用写法。坐标按 agentbase-sdks 当前发布面 v2.12.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.12.0"
curl -fsSL -o "$BUNDLE_DIR/agentbase-python-sdk-2.12.0.zip" "$BASE_URL/agentbase-python-sdk-2.12.0.zip"
curl -fsSL -o "$BUNDLE_DIR/agentbase-console-python-sdk-2.12.0.zip" "$BASE_URL/agentbase-console-python-sdk-2.12.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.12.0.zip" -d "$BUNDLE_DIR"
unzip "$BUNDLE_DIR/agentbase-console-python-sdk-2.12.0.zip" -d "$BUNDLE_DIR"
(cd "$BUNDLE_DIR/agentbase-python-sdk-2.12.0" && sha256sum -c SHA256SUMS)
(cd "$BUNDLE_DIR/agentbase-console-python-sdk-2.12.0" && sha256sum -c SHA256SUMS)
pip install "$BUNDLE_DIR/agentbase-python-sdk-2.12.0/agentbase_python_sdk-2.12.0-py3-none-any.whl"
pip install "$BUNDLE_DIR/agentbase-console-python-sdk-2.12.0/agentbase_console_python_sdk-2.12.0-py3-none-any.whl"不要安装开源 appwrite 官方包冒充 Agentbase Python SDK——它缺少 TablesDB、Knowledge Bases 等 Agentbase 扩展 surface。
Server SDK 初始化
agentbase 包的 __init__ 为空,全部符号按模块导入:
Python Server SDK 2.12.0 的默认请求可能在跳转时转发项目 API Key,暂不提供本段的 SDK 调用代码。可按 Python REST 请求示例 调用。
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(
'<APPBASE_ENDPOINT_WITH_V1>/account/sessions/email',
headers={'X-Appwrite-Project': 'console', 'Content-Type': 'application/json'},
json={'email': CONSOLE_EMAIL, 'password': CONSOLE_PASSWORD},
allow_redirects=False,
timeout=10,
)
if resp.status_code != 201:
raise RuntimeError(f'Console login failed: HTTP {resp.status_code}')
secret = re.search(r'a_session_console=([^;]+)', resp.headers['set-cookie']).group(1)
console_client = (
ConsoleClient()
.set_endpoint('<APPBASE_ENDPOINT_WITH_V1>')
.set_project('console')
)
console_client.add_header('origin', '<APPBASE_CONSOLE_ORIGIN>')
console_client.add_header('x-forwarded-host', '<APPBASE_CONSOLE_HOST>')
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(建库、建表、行、查询)
建库、定义表结构、写入和查询见数据库 API。
要点:columns / indexes 为 dict 列表(生成器校验为 DatabaseColumnDefinition / DatabaseIndexDefinition),列/索引 type 以功能点文档数据库为准;增量列接口返回多为 202 异步任务;update_rows / delete_rows 无 queries 时作用全表,务必加 Query 过滤。
DocumentsDB 与事务
DocumentsDB 是 TablesDB 的 document 语义面(create_collection / create_document / list_documents…):
先创建事务,再提交操作,确认成功后提交事务。失败时检查状态并按需回滚。接口见数据库 API。
用户、团队与存储
service 方法同步返回 pydantic 模型:按字段名访问(如 user.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 模块源码为准。
错误处理
处理 REST 调用错误时检查 HTTP 状态和响应中的 type。