Docs
Contents

Python Example

Initialization and invocation examples for each feature of the Python Server SDK (agentbase package, snake_case) and the Console SDK (agentbase_console package). Coordinates follow the agentbase-sdks current release surface: v2.10.0 (final state of the ZIP artifact release), while (the 2.6.0 iteration has no verifiable installable artifacts; the gap is logged in changelogs/2.6.0.md); runtime requires Python 3.9+ with runtime dependencies requests and pydantic>=2,<3.

Retrieval and Installation (Offline Wheel)

Artifacts are not published to PyPI; install with pip after unpacking the release ZIP (on an intranet, use PIP_INDEX_URL to point to a private mirror for dependencies):

BUNDLE_DIR="$(mktemp -d)"
BASE_URL="https://code.alipay.com/obai/agentbase-sdks/releases/download/v2.10.0"
curl -fsSL -o "$BUNDLE_DIR/agentbase-python-sdk-2.10.0.zip" "$BASE_URL/agentbase-python-sdk-2.10.0.zip"
curl -fsSL -o "$BUNDLE_DIR/agentbase-console-python-sdk-2.10.0.zip" "$BASE_URL/agentbase-console-python-sdk-2.10.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.10.0.zip" -d "$BUNDLE_DIR"
unzip "$BUNDLE_DIR/agentbase-console-python-sdk-2.10.0.zip" -d "$BUNDLE_DIR"
(cd "$BUNDLE_DIR/agentbase-python-sdk-2.10.0" && sha256sum -c SHA256SUMS)
(cd "$BUNDLE_DIR/agentbase-console-python-sdk-2.10.0" && sha256sum -c SHA256SUMS)

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

Do not install the open-source appwrite official package as a stand-in for the Agentbase Python SDK — it lacks Agentbase extension surfaces such as TablesDB and Knowledge Bases.

Server SDK initialization

The agentbase package's __init__ is empty; all symbols are imported per module:

from agentbase.client import Client

client = (
    Client()
    .set_endpoint('https://appbuild.oceanbase.com/v1')   # Includes /v1; SIT is https://appbuild-sit.oceanbase.com/v1
    .set_project('<PROJECT_ID>')
    .set_key('<SERVER_API_KEY>')                          # Project API Key with minimal scope, stored server-side only
)

ClientOther configuration (all chained, returning Client): set_organization(value) (required for organization-level queries), set_jwt(value) / set_session(value) (only for controlled flows where the endpoint explicitly requires user identity; not a general substitute for an API Key), set_self_signed(status) (self-signed TLS environments), add_header(key, value).

Console SDK initialization

The Console login response body does not contain the session secret (it is only in the a_session_console cookie); first log in via raw HTTP to get the cookie, then attach it to the 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}')

The Console service surface (agentbase_console.services) includes account, teams, projects, users, proxy, migrations, etc.; method names are snake_case like the Server package. The Console package and Server package can coexist in the same environment.

TablesDB (Databases, Tables, Rows, Queries)

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,
)

Key points: columns / indexes take lists of dicts (generators are validated as DatabaseColumnDefinition / DatabaseIndexDefinition); for column/index type, follow the feature documentation Databases; the incremental column interfaces mostly return 202 asynchronous tasks; update_rows / delete_rows without queries act on the entire table, so always add a Query filter.

DocumentsDB and transactions

DocumentsDB is the document semantic surface of TablesDB (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)   # Or rollback=True to roll back

Users, teams, and storage

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'),   # Or InputFile.from_bytes(b'...', 'report.txt', 'text/plain')
)
data: bytes = storage.get_file_view(bucket_id='attachments', file_id='<file-id>')

Service methods return pydantic models synchronously: access by field name (user.id, created['$id'] see above); the model_type parameter only types the business data payload of documents / rows. The response body of a server-created user session contains no secret (only in the a_session_<projectId> cookie); to get a user-context client, read that cookie and then Client().set_session(secret).

Memory / Knowledge Bases / gateway and observability

Themed capabilities (Memory, Knowledge Bases, LLM Gateway, AI Gateway, Observability, Moderation, Messaging, Sites, etc.) each have a corresponding module under agentbase.services, with unified construction via Xxx(client); the method surface is isomorphic to the Node SDK (snake_case), and Python has completed the Knowledge Bases invocation surface since 15.4.0. For parameters and return structures, see each feature's documentation (agent workbench, memory, knowledge base, LLM and AI Gateway, observability, etc.); for JavaScript equivalents, see the corresponding sections of javascript.md; per-field Python signatures follow the agentbase.services module source code.

Error Handling

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 is the HTTP status code: 404 / 429 / 401·403; type is the server-side error type