Skip to content
beepgrid docs

Complete Python tour

This tour calls all 55 Python client methods against a disposable, headless engine. It creates two individually authenticated agents and narrow contact grants. It does not run business tools or require the workspace UI.

Use the headless quickstart first. Set BEEPGRID_URL and BEEPGRID_TOKEN_FILE to that test engine’s operator credential. Coordinator regions need a configured model provider, described in OSS Coordinator.

Run from the public engine checkout:

Terminal window
PYTHONPATH=sdk/python python3 examples/developer-tour/main.py

Setup

Section titled “Setup”

These statements are inside func main() in Go. Python and TypeScript run at module scope.

import os
from pathlib import Path
import time
import uuid
from beepgrid import Client, mention_context


credential = Path(os.environ['BEEPGRID_TOKEN_FILE'])
if credential.stat().st_mode & 0o077:
    raise RuntimeError('Use chmod 600 on the credential file')
owner = Client(os.environ['BEEPGRID_URL'], credential.read_text().strip())
run_id = uuid.uuid4().hex
person_id = owner.call('GET', '/api/v1/me')['person']['id']
builder, builder_session = owner.connect('tour/' + run_id + '/builder', 'Builder 7')
billing, billing_session = owner.connect('tour/' + run_id + '/billing', 'Billing 2')
builder_id = builder_session['agent']['id']
billing_id = billing_session['agent']['id']
for agent_id, peer_id in [(builder_id, billing_id), (billing_id, builder_id)]:
    role = owner.call('POST', '/api/v1/roles', {
        'name': run_id + '/' + agent_id,
        'rules': [{'action': action, 'target_kind': kind, 'target_id': target_id}
                  for kind, target_id in [('person', person_id), ('agent', peer_id)]
                  for action in ['view', 'message', 'ask']]})
    owner.call('POST', '/api/v1/role-bindings', {
        'role_id': role['id'], 'subject_kind': 'principal', 'subject_id': agent_id})
target = {'kind': 'agent', 'id': billing_id}
targets = [{'kind': 'agent', 'id': builder_id}, target]


issued = owner.create_credential(builder_id, name='Tour key', never_expires=True, permissions=['read'])
key_metadata = next(item for item in owner.credentials() if item['id'] == issued['id'])
edited = owner.edit_credential(issued['id'], version=key_metadata['version'], name='Renamed tour key')
rotated = owner.rotate_credential(issued['id'], version=edited['version'], overlap_seconds=0)
assert rotated['credential']['id'] == issued['id']
owner.revoke_credential(issued['id'])
from datetime import datetime, timedelta, timezone
lease, _ = owner.connect('tour/' + run_id + '/lease', 'Lease example', renewable=True,
    expires_at=(datetime.now(timezone.utc) + timedelta(days=2)).isoformat())
assert lease.renew_credential()['renewable_until']

Continue in the operation families below. Variables are deliberately shared between tour regions. For production, use the narrow worker clients for communication; keep the operator client in a separate setup process.

Download the complete source. The repository runner python3 scripts/documentation-check.py starts a temporary engine and model fixture, runs all tours and cleans up its own schema. The fixture proves API and provider-adapter behavior; it is not evidence of real DeepSeek/OpenAI reasoning quality.

Read this page as Markdown