PYB Agent SDK (Python)

Python client SDK for the PYB Agent engine — with a built-in engine launcher: pip install is all you need; the SDK auto-discovers or spawns the engine on first use (zero-prerequisite install on platforms with a bundled wheel).

Install

pip install pyb-agent-sdk

• Windows x64: a platform wheel with the bundled engine is selected automatically (py3-none-win_amd64, ~67MB) — no other setup needed.
• Other platforms: the pure wheel installs the launcher, which reuses a running engine at http://localhost:4096 or spawns the pyb command from PATH (npm install -g pybao-xc-sdk provides it).

Quick start

import asyncio
from pyb_agent_sdk import PybAgentClient, ClientOptions

async def main():
    async with PybAgentClient(
        "http://localhost:4096",          # probed first; auto-spawn if dead
        options=ClientOptions(cwd="D:/proj"),
    ) as client:
        async for event in client.query("hello"):
            if event.type == "content_delta":
                print(event.text, end="")

asyncio.run(main())

First-run model configuration

The engine starts without credentials, but conversations require a model API key. Two options:

1. Interactive: run pyb once in a terminal and complete model setup — stored in ~/.pyb/model-config-v2.sqlite.
2. Environment: set ANTHROPIC_AUTH_TOKEN=<your key> before starting your Python process.

GLM keys: https://open.bigmodel.cn (the engine's default model family).

Without a key, the first query() fails with an actionable message pointing here (the engine's /health stays green — key issues surface per-turn, not at startup).

Engine version lock

The launcher validates the spawned engine's --version against a known-good floor (currently 1.5.281) and fails fast with upgrade guidance if the binary is older — instead of mysterious mid-conversation protocol errors.

Session pinning (shared live context)

Pass session_id= to the constructor to attach to an existing session — all clients on the same session share live context (server-side broadcast), e.g. ESP32 voice input and terminal CLI in one conversation.

API surface

• PybAgentClient(base_url, *, session_id=None, options=None, can_use_tool=None)
• await client.start() → session_id / await client.resume(session_id)
• async for event in client.query(text) — content_delta / terminal events
• await client.interrupt() — abort the running turn
• SessionLostError — first-class: raised when the server lost the session