Skip to main content

zoowork

Official Python SDK for the ZooWork Managed Agents API. Developer Preview.

The client is asynchronous, typed, and built on httpx. Request and response fields retain the public API's wire spelling, while methods use Python snake_case.

pip install zoowork

Quickstart

Create a Project API key (zwp_live_...) in ZooWork Platform and keep it on your server. It scopes Agent and Session access to that Project. Platform runtime creation requires initialized Organization billing and bound owner credentials; rebind the key after signing in when the API requests it.

import asyncio
import os

from zoowork import assistant_text, create_zoowork_client, is_run_finished


async def main() -> None:
    async with create_zoowork_client(os.environ["ZOOWORK_API_KEY"]) as client:
        models = await client.list_models()
        primary = next(
            model["model"]
            for model in models
            if model.get("selectable", True)
            and model["model"] == "litellm/gpt-5.6-terra"
        )
        agent = await client.create_agent(
            {"name": "research-agent", "model": {"primary": primary}}
        )
        agent_id = agent["agent_id"]

        await client.start_agent(agent_id)
        await client.wait_until_running(agent_id)
        session = await client.create_session(
            agent_id,
            {"initial_events": [{"type": "user.message", "content": "What can you do?"}]},
        )

        async for event in client.stream_events(agent_id, session["session_id"]):
            print(assistant_text(event), end="", flush=True)
            if is_run_finished(event):
                break


asyncio.run(main())

Set ZOOWORK_API_KEY and call create_zoowork_client() with no argument if you prefer. The client uses the production API by default; ZOOWORK_BASE_URL or base_url= selects another deployment.

list_models() can include rows whose retirement has started. Check model.get("selectable", True) before using a row in a new Agent or config. A non-selectable choice returns 409 model_not_selectable; expired_fallback_to contains the reviewed replacement when present.

To set a default thinking level, read the levels a model supports from list_models() and choose one in model.thinking ("off", "low", "medium", "high" or "max"; the ThinkingLevel alias is exported). Omit it to use the platform default; send "thinking": None in an update_agent call to clear it. A schedule's agentTurn payload accepts the same thinking values.

from zoowork import ThinkingLevel, ZooworkClient


async def create_tuned_agent(client: ZooworkClient, primary: str) -> dict:
    wanted: ThinkingLevel = "high"
    models = await client.list_models()
    info = next(m for m in models if m["model"] == primary)
    supported = info.get("thinking", {}).get("levels", [])  # absent on older servers

    model = {"primary": primary}
    if wanted in supported:
        model["thinking"] = wanted
    # Otherwise leave `thinking` unset so the Agent follows the platform default.
    return await client.create_agent({"name": "deep-research-agent", "model": model})

Agent resource mappings also accept userTimezone, a named IANA timezone for prompt and message time context, and include_global_skills: False to disable automatic global Skills while preserving explicit installs. "skills": [] also opts out. Schedule timezones are configured separately.

create_session accepts isolation ("shared" or "session"). "session" isolates the Session's workspace, Memory, FileRef and Artifact from other Sessions; it does not isolate the Agent owner's platform identity, GitHub, browser logins or model billing rights. See the owner credential boundary in the Vault section.

Pagination

list_agents() returns one AgentPage. Iterate the page to continue lazily through every remaining page while retaining the original filters:

page = await client.list_agents(labels={"project": "research"})
print(page.data, page.total, page.next_page)

async for agent in page:
    print(agent["agent_id"])

Use await page.get_next_page() for manual navigation or client.iter_agents() when you do not need the first page's metadata.

Durable events

The event stream is session-scoped and does not close when one turn ends. Break on is_run_finished(event). Save event.cursor after consuming an event and pass it back as cursor= when reconnecting. Do not pass event.seq as after=: after is deprecated and reads the engine-only lane, which numbers events differently and omits your inputs, so events are silently skipped. Type checkers flag calls that pass after. Listed events carry no cursor; continue a listing from the page's next_cursor, which list_all_events(cursor=...) also accepts.

async for event in client.stream_events(agent_id, session_id, cursor=last_cursor):
    if event.cursor is not None:
        last_cursor = event.cursor
    if is_run_finished(event):
        break

list_events() reads one durable page. list_all_events() follows cursor pagination, with a safe fallback for older deployments.

Agent tools and channels

Agent resources keep the API's original field names. MCP runtime context is opt-in and is not authentication. permission sets the server default; tools overrides exact native tool names. Tool-policy selectors accept an exact name, global *, or one trailing prefix*.

agent = await client.create_agent(
    {
        "name": "support-agent",
        "mcp": [
            {
                "name": "operations",
                "url": "https://mcp.example.com",
                "context": {"meta": True},
                "permission": "always_ask",
                "tools": {"lookup_customer": {"permission": "always_allow"}},
            }
        ],
    }
)

Project keys use the managed Environment. Root Environment and Skill administration return 404 service_api.not_found. Inspect attached Skills with list_agent_skills. At create time, each skills entry needs a skill_id and stays on the version resolved at creation, including "latest"; to keep a Skill on the newest version, assign it after creation with put_agent_skill and no version_pin. An entry with name makes the list the Agent's exact Skill set, drops global Skills, and makes later assignment calls return 409 source_owned_skills.

Channels connect WeChat, WeCom, Feishu, Slack or DingTalk to an Agent. Each Agent has one connection per platform: omit account or pass "default". Use start_channel_setup and wait_for_channel_setup for the QR platforms (feishu, wecom, weixin) and add_channel with app credentials for the others.

Filtered sessions and application-executed tools

list_sessions() keeps the legacy numeric page. list_session_page() selects the filtered cursor lane and starts with sls1:0. Its cursor is opaque and valid only with the same channel, surface, runtime-mode and archive filters; use each row's list_cursor or the page's next_cursor to continue.

Pass include_deleted=True to include deletion tombstones for reconciliation. Returned rows then carry deleted, and the page has includes_deleted=True. This flag is part of the cursor scope, so do not reuse a cursor created without it.

Declare application-executed tools in resource.custom_tools. At most 32 declarations are accepted. A declaration has name, description, an object input_schema, and optional timeoutMs (default 600,000 ms; maximum 86,400,000 ms).

When custom_tool_use(event) returns a requested call, execute it in your application and return the result with resolve_custom_tool_call(). list_custom_tool_calls(status="pending") recovers pending work after a restart. You can instead post user.custom_tool_result to the owning session. While paused, run_status is awaiting_approval; check pending_custom_tool_calls to distinguish it from a normal approval.

from zoowork import custom_tool_use

call = custom_tool_use(event)
if call is not None and call.phase == "requested":
    await client.resolve_custom_tool_call(
        agent_id,
        call.call_id,
        content=[{"type": "json", "value": {"price": 42}}],
        resolved_by="pricing-service",
    )

Result content contains 1–16 text, JSON, or base64 image blocks. Use an idempotency key when posting the session event. A pending REST resolution returns signaled: true before the row becomes terminal; signaled: false means it was already completed, timed out, or cancelled. This lifecycle is source-reviewed and still needs deployment verification.

Receiving webhooks

verify_webhook_signature() and unwrap_webhook() verify a received webhook using the standard library only. Pass the request bytes exactly as received: a re-serialized JSON body no longer matches the signature. The signature is checked before the body is parsed, so unverified bytes never reach the JSON parser. Supply accept_once using your durable storage and queue; a worker performs business processing after acknowledgement.

from zoowork import WebhookSignatureError, run_id, unwrap_webhook


def application(environ, start_response):
    length = int(environ.get("CONTENT_LENGTH") or 0)
    raw_body = environ["wsgi.input"].read(length)
    headers = {
        key[5:].replace("_", "-"): value
        for key, value in environ.items()
        if key.startswith("HTTP_")
    }
    try:
        event = unwrap_webhook(headers=headers, raw_body=raw_body)
    except WebhookSignatureError as error:
        start_response("400 Bad Request", [("content-type", "text/plain")])
        return [error.code.encode()]
    if event.id != headers.get("WEBHOOK-ID"):
        start_response("400 Bad Request", [])
        return []
    try:
        accept_once(event.id, event)  # atomic durable insert + worker item; duplicates succeed
    except Exception:
        start_response("503 Service Unavailable", [])
        return []
    start_response("204 No Content", [])
    return []

headers accepts any case-insensitive container: a plain dict, a single-valued mapping of lists, or a headers object with get(). secret defaults to ZOOWORK_WEBHOOK_SECRET, which may hold every active secret of a rotation window separated by whitespace or commas; pass secret=["whsec_...", "whsec_..."] when configuration comes from elsewhere. The timestamp window is ±300 seconds (tolerance_seconds) and the body ceiling is 16 KiB (max_body_bytes).

unwrap_webhook() returns a frozen WebhookEvent with the envelope's own field names: object, id, type, schema_version, created_at and data. The frame is validated strictly — object must be "event", id, type and created_at must be strings, schema_version must be present and an integer value (a JSON number, 1 or 1.0, never 1.5; it is read back as an int), and data must be an object — because the server sends all of them on every envelope and the TypeScript SDK rejects the same ones. type keeps the server's string even when this release does not know it, because event types are added server-side; check is_known_webhook_event_type() against WEBHOOK_EVENT_TYPES and ignore what you do not handle. data is passed through unchanged, and session_id(), run_id(), agent_id() and schedule_id() read its common fields.

Failures raise WebhookSignatureError, a ZooworkError with status 400 and a stable code: invalid_secret, body_too_large, missing_header, invalid_header, timestamp_out_of_window, signature_mismatch, or invalid_payload. Match the code, never the message; messages never contain a secret, a signature, or body bytes. The code is the cross-language contract: the TypeScript SDK raises its own standalone error class with the identical codes, so a repeated header or a malformed envelope is rejected the same way on both sides.

The wire format is plain Standard Webhooks, so a receiver can equally verify with the official PyPI standardwebhooks package. This SDK is byte-compatible with it: tests/fixtures/webhook_vectors.json is the fixed vector file the server and the TypeScript SDK assert against, copied verbatim.

Vault (beta)

Beta. Vault is open in the ZooWork production environment. An account or environment where it is not enabled still gets 404 service_api.not_found from the Vault methods, and 400 vault.session_fields_unavailable from create_session with Vault fields. The SDK raises VaultBetaUnavailableError for both (check with is_vault_beta_unavailable(err)); err.type keeps the server code. Behaviour and fields may change before general availability.

Verification: the public two-user acceptance (TypeScript and Python SDK profiles) passed on staging against Engine v0.2.50-beta.3. Production enabled the public Vault API on 2026-11-09; its canary is an Engine-side canary, not run by this SDK.

Owner credential boundary. isolation="session" isolates a Session's VM, /workspace, Memory, FileRef and Artifact from other Sessions. It does not isolate the Agent owner's platform identity, GitHub, browser logins or model billing rights: model-driven code in the sandbox can still use the owner's credentials. MCP credentials stored in a Vault do not themselves enter the sandbox environment variables. Session isolation is not owner-credential isolation.

How beta is marked. Python has no standard beta annotation, so this SDK uses one convention: the docstring of every beta method, class, function, type alias and constant starts with Beta., and create_session's docstring has a Beta: paragraph for its Vault fields. The Vault types and helpers live in zoowork.vault and are re-exported from zoowork; the Vault methods are the *vault* methods of ZooworkClient. A test keeps the marking complete.

A Vault stores credentials for an Agent's MCP servers. A Session created with vault_ids uses them; responses never return a secret.

Declare the MCP server on the Agent first. The Engine uses a Vault credential only for an MCP server that the Agent declares with auth: {"type": "vault"}. Such a server has no credential (an entry cannot carry both auth and credential) and its url is an HTTPS URL that contains no credentials; the credential comes from the Session's Vault binding. Agent resources are plain dicts in this SDK, so nothing extra is imported:

agent = await client.create_agent(
    {
        "name": "support-agent",
        "mcp": [{"name": "github", "url": "https://mcp.example/github", "auth": {"type": "vault"}}],
    }
)

The Vault credential's mcp_server_url below must match that server's url.

Vault needs a Platform API key. A project key manages its project's Vaults. Use the Default Project key for org Vaults: a project key cannot read or manage them (403 vault.management_forbidden).

vault = await client.create_vault(
    {"scope": "project", "project_id": "proj_…", "name": "user-a", "metadata": {"user": "a"}},
    idempotency_key="vault-user-a",
)
await client.create_vault_credential(
    vault["id"],
    {
        "name": "github",
        "purpose": "mcp",
        "provider_account_ref": "gh-user-a",
        "auth": {
            "type": "static_bearer",
            "mcp_server_url": "https://mcp.example/github",
            "access_token": token,
        },
    },
    idempotency_key="cred-user-a-github",
)

session = await client.create_session(
    agent_id,
    {
        "isolation": "session",  # required with vault_ids; `session` for a multi-user Agent
        "vault_ids": [vault["id"]],
        "external_user_ref": "user-a",  # a label for your records, not an authorization
        "initial_events": [{"type": "user.message", "content": "List my open issues"}],
    },
    idempotency_key="session-user-a-1",  # required with Vault fields
)
save_binding(session["session_id"], session["vault_binding"]["revision"])  # for revoke/offboarding

Rules:

  • One logical operation, one idempotency_key. Retry a timeout or 503 vault.unavailable with the same key. A key reused for another request (another Vault, another body) is 409 vault.idempotency_conflict. Every Vault write requires a non-empty key; None or "" raises ValueError before sending.
  • Update, archive, delete and revoke take revision (sent as If-Match). A stale one is 412 vault.revision_conflict: read the resource again. validate_vault_credential takes neither key nor revision. The write methods accept no other options, so nothing else reaches the wire.
  • A retried delete that answers 404 vault.not_found already succeeded.
  • With Vault fields, create_session needs isolation set to "shared" or "session" and a non-empty idempotency_key; otherwise it raises ValueError before sending. Omit the Vault fields you do not use; one that is present, even None or [], makes the request a Vault request. Nested mappings and tuples in any Vault body are sent as JSON objects and arrays.
  • Read credential["health"] through vault_credential_health_state(credential). Only ok is healthy. Show a re-authorize prompt on reauthorization_required and a rotate prompt on expired (update_vault_credential). A state the SDK does not know reads as unknown.
  • A Session's Vault errors carry two spellings. Session routes answer the dotted code at the top level ("code": "vault.binding_revoked") and keep Engine's code in error.type (vault_binding_revoked), which is what err.type holds. Match with vault_session_error_code(err): it reads the top-level vault.* code when present, accepts either spelling otherwise, and returns the dotted one (vault.binding_revoked, vault.binding_expired, vault.profile_restricted).

Where this SDK checks more than the TypeScript SDK. The Vault design requires an SDK to send isolation explicitly whenever a Session carries credentials; today the server defaults an omitted one to session there, and it will tighten to 400 isolation_required. The TypeScript SDK enforces that rule, and the idempotency key, with types at compile time. Python has no equivalent type-level check, so create_session checks both at runtime before sending. It is the same rule, not a different API behaviour.

When a user leaves, either archive or delete that user's dedicated Vault or credential (every Session using it is refused at its next call), or revoke that user's Sessions. ZooWork does not model end users, so your application keeps the user → Session mapping:

ledger = await client.create_vault_offboarding(
    {
        "sessions": [{"agent_id": agent_id, "session_id": session_id, "revision": revision}],
        "external_user_ref": "user-a",
    },
    idempotency_key="offboard-user-a",
)
current = ledger
deadline = time.monotonic() + 600
while current["status"] == "in_progress" and time.monotonic() < deadline:
    await asyncio.sleep(30)
    current = await client.get_vault_offboarding(ledger["id"])
# Still `in_progress` at the deadline: the service keeps retrying; read the ledger again later.
# `completed`: every Session revoked. `incomplete`: check each Session's `state`;
# `not_found` is NOT a revocation.

revoke_session_vault_binding(agent_id, session_id, idempotency_key=..., revision=...) revokes one Session directly. Its 404 service_api.not_found can mean an unknown Agent or Session as well as Vault not being enabled, so it is raised as a plain ZooworkError naming both causes, not as VaultBetaUnavailableError. See examples/vault.py.

API surface

The runtime client follows the TypeScript SDK's public capabilities:

  • agents, lifecycle, models and paginated listing;
  • channels, direct DingTalk, and guided Feishu/WeCom/WeChat setup;
  • skill upload, versioning and agent attachment;
  • sessions, filtered cursor listing, application-executed custom tools, events and SSE streaming;
  • approvals, artifacts and system prompts;
  • schedules, wake, sandbox exec and file upload into the sandbox (upload_file);
  • Environments and immutable Environment versions.
  • beta: Vault and credential management, the Vault fields of create_session, Session Vault-binding revoke and the offboarding ledger (see Vault (beta)).

Methods return dictionaries containing the API response unchanged unless the SDK must normalize pagination or events. Unknown fields are intentionally preserved.

Errors

Every non-successful response raises ZooworkError. Match error.type or error.status, never the human-readable message. Diagnostic fields include content_type, body_snippet (the first 600 characters of the body), cf_ray, request_id, and retryable. code is the body's top-level string code, read from the whole body; when it differs from type (a mapped envelope), the dotted code is in code. It is not WebhookSignatureError.code.

Development

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest
python -m ruff check .
python -m mypy src
python -m build
python -m twine check dist/*

Unit tests are offline. The live staging procedure is documented in e2e/README.md and is never run by CI.

Developer API helpers

Check the installed SDK for these methods; if a release lacks one, use the documented HTTP endpoint. These examples require a release containing the helpers.

usage = await client.get_usage(range="7d", view="both")
balance = await client.get_balance()  # {"object": "balance", "available_amount": "11.34", "currency": "usd"}
endpoint = await client.create_agent_webhook(
    agent_id, {"url": "https://receiver.example/webhook", "event_types": ["run.finished"]},
    idempotency_key="register-hook-v1",
)
# Save signing_secret securely when present; an idempotent replay may return None.
hooks = await client.list_agent_webhooks(agent_id)  # hooks["webhooks"]
output = await client.get_run_output(agent_id, session_id, run_id)
approvals = await client.list_approval_page(agent_id, session_id=session_id)

The workspace Files methods (get_workspace_file, write_workspace_file, get_workspace_file_content) are deprecated: the hosted service does not enable those routes. Send a file to an Agent with upload_file, and retrieve results by asking the Agent to publish Artifacts and downloading those through the Artifact API. The database viewer is not a supported production workflow. The Agent can use agent_db and return query results in its reply. Method presence is not production availability. Usage stays within current key scope. get_balance returns the Organization balance shared by all Projects, in USD, to any Platform key in the Organization. Paging returns next_cursor and has_more unchanged. get_approval and get_custom_tool_call read terminal as well as pending actions. Existing array-returning list methods remain available.

Webhook management includes get/update/delete, rotate_agent_webhook_secret, test_agent_webhook, get_agent_webhook_event, delivery list/detail and single/batch redelivery. Create, rotation, test and redelivery require a stable idempotency_key; SDK mutations never retry automatically. A 202 receipt acknowledges queuing. Query deliveries for the outcome; for a test, pass the test receipt's receipt_id as receipt_id=.

Session input accepts runtime_mode: "active" to pin the active configuration at creation; omission resolves active configuration on subsequent turns. idle_compaction preserves false, null and omission. MCP tool overrides support requireConfirmation.

Pass an optional positive expected_config_version in the update_agent sections mapping to check the current configuration version atomically with the update. Read it from (agent.get("status") or {}).get("config_version") or agent.get("config_version"). A mismatch raises ZooworkError with status 409 and type active_config_changed without changing the configuration. Re-read and recompute the intended change before retrying; the precondition itself is not stored in declared. Omitting it keeps last-write-wins behavior. Ownership-only changes do not increment configuration version. The separate upgrade_system_prompt method requires its version precondition and uses 409 config_version_changed.

Current production behavior

  • Manual Schedule execution requires enabled: true, which also enables automatic firings. A disabled Schedule can return triggered: true and still be skipped. The receipt is not a run result; run rows can lack status/session linkage.
  • Approval waiting is agent.approval / requested; resolved ends the approval wait. agent.tool / blocked ends a call without execution, with no later end. Reasons include policy denial, approval denial/timeout/cancellation, or interruption; inspect the event payload's deniedReason.
  • Save each processed stream cursor with its Session ID. Pass it when reading a subsequent turn in that Session. No cursor means replay from the beginning, including old run.finished. REST events and post-event receipts do not supply a cursor; the last REST page has a null continuation token. There is no current-tail helper. Without a saved cursor, replay and reconstruct state or deliberately start a new conversation; do not synthesize a cursor from seq.
  • First Agent deletion succeeds with 204; repeated deletion returns 404 through the public API. For cleanup retries, interpret 404 as absence only for a known Agent with unchanged key scope. Other-tenant or inaccessible resources also return 404.
  • Invalid Usage parameters can return either 400 usage.invalid_query or 422 with no business error type. Correct the parameters rather than retrying unchanged. Match status as well as type.

See the public guides for supported workflows. These notes do not change SDK transport behavior or make unavailable endpoints usable.

Metadata

Release files for zoowork 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zoowork 0.10.0
File Size Uploaded Provenance Actions
zoowork-0.10.0.tar.gz 103.6 kB With provenance Details for zoowork-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zoowork 0.10.0
File Interpreter ABI Platform Actions
zoowork-0.10.0-py3-none-any.whl Python 3 none any Details for zoowork-0.10.0-py3-none-any.whl

Total release size: 159.4 kB

Release files / zoowork-0.10.0.tar.gz

Download URL zoowork-0.10.0.tar.gz
Size 103.6 kB
Tags Source
SHA-256 checksum
How to use checksums
91ddb4a9a36a75dbf604306b3e49ba3fe22bdd942a11ad244ac7d907ac03c69e
BLAKE2b-256 checksum
How to use checksums
6c28cc7e3a91b9d1ade99d151faf3327dd0df951b850b6e062c7adcae78bd30d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / zoowork-0.10.0-py3-none-any.whl

Download URL zoowork-0.10.0-py3-none-any.whl
Size 55.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e3e42eef21697258d752855fe9f9ac27224f58a87eb3467e67701473d42f2b3f
BLAKE2b-256 checksum
How to use checksums
7ea41b366079fe62fe6b31ba4866dd92b8c9f5d3218a2d51d6af4bac6864def6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for zoowork 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zoowork-0.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page