Zag Python Binding

Python binding for zag — a unified CLI for AI coding agents.

Prerequisites

• Python 3.10+
• The zag CLI binary installed and on your PATH (or set via ZAG_BIN env var)

Installation

pip install zag-agent

For development from source:

cd bindings/python
pip install -e .

Quick start

from zag import ZagBuilder

output = await ZagBuilder() \
    .provider("claude") \
    .model("sonnet") \
    .auto_approve() \
    .exec("write a hello world program")

print(output.result)

Streaming

from zag import ZagBuilder

async for event in await ZagBuilder().provider("claude").stream("analyze code"):
    print(event.type, event)

Builder methods

Provider support for streaming / MCP flags

Four builder methods that toggle streaming I/O details and per-invocation MCP configuration are only honored by the Claude provider. Passing them to any other provider is a no-op.

.exec_streaming() is Claude-only and always sets -i stream-json, -o stream-json, and --replay-user-messages. By default it emits one assistant_message event per complete assistant turn — you get one event when the model finishes speaking, not a stream of token chunks. Call .include_partial_messages(True) to receive token-level partial assistant_message chunks instead. The default stays False so existing callers that render whole-turn bubbles are not broken.

At the end of every agent turn the session emits a turn_complete event carrying the provider's stop_reason (end_turn, tool_use, max_tokens, stop_sequence, or None), a zero-based monotonic turn_index, and the turn's usage. A per-turn result event fires immediately after. New code should key turn-boundary UI off turn_complete — it is the authoritative signal and carries richer metadata than result. result continues to fire per-turn for backward compatibility.

Terminal methods

Version checking

The SDK automatically checks the installed zag CLI version before running commands. If you use a builder method that requires a newer CLI version than what's installed, a clear error is raised:

env() requires zag CLI >= 0.6.0, but the installed version is 0.5.0.
Please update the zag binary.

The version is detected once (by running zag --version) and cached for the lifetime of the process.

All other methods are available since the initial release (0.2.3).

Discovery

Standalone async functions for discovering available providers, models, and capabilities:

from zag import list_providers, get_capability, get_all_capabilities, resolve_model

providers = await list_providers()
cap = await get_capability("claude")
all_caps = await get_all_capabilities()
resolved = await resolve_model("claude", "small")  # ResolvedModel(input="small", resolved="haiku", is_alias=True)

How it works

The SDK spawns the zag CLI as a subprocess (zag exec -o json or -o stream-json) and parses the JSON/NDJSON output into typed dataclasses. Zero external dependencies — only the Python standard library.

Testing

pip install pytest pytest-asyncio
pytest

See also

• TypeScript SDK
• C# SDK
• Rust API (zag-agent)
• All bindings

License

MIT