zag-agent 0.8.3

Python SDK for zag — a unified CLI for AI coding agents

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

Method	Description
.provider(name)	Set provider: "claude", "codex", "gemini", "copilot", "ollama"
.model(name)	Set model name or size alias ("small", "medium", "large")
.system_prompt(text)	Set a system prompt
.root(path)	Set the working directory
.auto_approve()	Skip permission prompts
.add_dir(path)	Add an additional directory (chainable)
.file(path)	Attach a file to the prompt (chainable)
.env(key, value)	Add an environment variable for the agent subprocess (chainable)
.json_mode()	Request JSON output
.json_schema(schema)	Validate output against a JSON schema (implies .json_mode())
.json_stream()	Enable streaming NDJSON output
.worktree(name=None)	Run in an isolated git worktree
.sandbox(name=None)	Run in a Docker sandbox
.session_id(uuid)	Use a specific session ID
.output_format(fmt)	Set output format ("text", "json", "json-pretty", "stream-json")
.input_format(fmt)	Set input format ("text", "stream-json" — Claude only)
.replay_user_messages()	Re-emit user messages on stdout (Claude only)
.include_partial_messages()	Include partial message chunks (Claude only)
.max_turns(n)	Set the maximum number of agentic turns
.timeout(duration)	Set a timeout duration (e.g., "30s", "5m", "1h"). Kills the agent if exceeded.
.mcp_config(config)	MCP server config: JSON string or file path (Claude only)
.show_usage()	Show token usage statistics (JSON output mode)
.size(size)	Set Ollama model parameter size (e.g., "2b", "9b", "35b")
.verbose()	Enable verbose output
.quiet()	Suppress non-essential output
.debug()	Enable debug logging
.bin(path)	Override the zag binary path

Terminal methods

Method	Returns	Description
.exec(prompt)	AgentOutput	Run non-interactively, return structured output
.stream(prompt)	AsyncGenerator[Event]	Stream NDJSON events
.exec_streaming(prompt)	StreamingSession	Bidirectional streaming (Claude only)
.run(prompt=None)	None	Start an interactive session (inherits stdio)
.resume(session_id)	None	Resume a previous session by ID
.continue_last()	None	Resume the most recent session

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.

Method	Minimum CLI version
.env()	0.6.0
.mcp_config()	0.6.0

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)

Function	Description
list_providers(bin=None)	List available provider names
get_capability(provider, bin=None)	Get capabilities for a provider
get_all_capabilities(bin=None)	Get capabilities for all providers
resolve_model(provider, model, bin=None)	Resolve a model alias

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