CLI and agent protocols

TypeScript provides a Stable schema-backed command contract for local development, inspection, workflows, artifacts, and evaluations. Python provides a Beta CLI plus Beta A2A v1, AG-UI, and a constrained OpenAI Responses-compatible host.

Capability	TypeScript	Python
Local inspect and run tooling	zhivex-ai	zhivex
Evaluation commands	Saved agent/workflow ledgers and fixtures	JSON datasets with repeated trials and report artifacts
Local browser playground	Not part of the documented CLI contract	zhivex playground
Protocol hosting	Build on application HTTP/SSE boundaries	A2A v1, AG-UI streaming, and a Responses-compatible subset
Stability	Stable	Beta

TypeScript CLI

Installing @zhivex-ai/sdk provides the zhivex-ai binary. Its inspection commands operate on local saved state; execution commands import an application-owned local module and may run its models and tools.

zhivex-ai init agent --dir support-agent --provider openai --model gpt-6-astra
zhivex-ai doctor --dir support-agent --provider openai

zhivex-ai sessions list --dir .zhivex/sessions
zhivex-ai artifacts verify \
  --dir .zhivex/artifacts \
  --app support \
  --user user_123 \
  --session session_456 \
  --id artifact_123

zhivex-ai agents ledger --state agent-run-state.json --out run-ledger.json
zhivex-ai agents golden --ledger run-ledger.json --name happy-path --out golden-trace.json
zhivex-ai agents eval --golden golden-trace.json --ledger run-ledger.json --out agent-eval.json

zhivex-ai workflow replay --state workflow-state.json
zhivex-ai workflow run \
  --module ./workflow.mjs \
  --input workflow-input.json \
  --state-out workflow-state.json

zhivex-ai workflow eval \
  --module ./workflow.mjs \
  --fixture workflow-eval.json \
  --report-out candidate.json
zhivex-ai workflow gate --candidate candidate.json --baseline baseline.json

The Stable contract covers command grammar, schema-backed JSON output, fail-closed argument validation, local workflow execution and inspection, and dry-run-first pruning. Agent ledgers omit full output text by default. Use --include-output-text only for a reviewed local destination. Prune commands are dry-run by default and require --execute to delete. The CLI does not add authentication, workspaces, or remote Gateway calls.

Python CLI

A Python agent reference uses module:attribute. Importing it executes the module, so load only reviewed local code.

zhivex inspect my_app.agents:support_agent
zhivex run my_app.agents:support_agent --prompt "Draft a reply" --json
zhivex eval my_app.agents:support_agent \
  --dataset evals/support.json \
  --repetitions 5 \
  --max-concurrency 4 \
  --min-pass-rate 0.95 \
  --output-json artifacts/evaluation.json \
  --output-junit artifacts/evaluation.xml

Install the API extra before using the local server or playground:

pip install "zhivex-ai-sdk[api]"
zhivex serve my_app.agents:support_agent --model-alias support
zhivex playground my_app.agents:support_agent --model-alias default

The playground binds to 127.0.0.1:8000 by default and rejects non-loopback hosts. It has no authentication. Use zhivex serve behind application-owned IAM, TLS, rate limits, tenancy, audit, and observability for any remote environment.

Python protocol adapters

Protocols transport an already configured Agent; they do not become the authorization or business-policy layer.

Protocol	Install	What it provides	Important boundary
A2A v1	pip install "zhivex-ai-sdk[a2a]"	Agent card, JSON-RPC v1, HTTP+JSON task operations, and streaming.	Clients must send A2A-Version: 1.0; replace process-local task state for production.
AG-UI	pip install "zhivex-ai-sdk[ag-ui]"	Official encoding for run, text, tool, finish, and error events.	The application owns thread state, reconnect, resume authorization, interrupts, and rendering.
Responses-compatible host	pip install "zhivex-ai-sdk[api]"	Strict text/message create, streaming, stored result, and event replay subset.	It is not a clone of every OpenAI Responses feature. Unknown or unsupported fields are rejected.

Serve A2A through the CLI for local integration work:

zhivex serve my_app.agents:support_agent \
  --protocol a2a \
  --public-url https://agents.example.com \
  --agent-version 1.0.0

For production, create the protocol app in application code so authorization and trusted runtime context are explicit:

from zhivex_ai import InMemoryResponsesEventStore, ProtocolLimits, create_responses_app

app = create_responses_app(
    agents={"support": support_agent},
    authorize=authorize_request,
    run_options_resolver=resolve_run_options,
    limits=ProtocolLimits(max_request_bytes=512_000, max_text_chars=32_000),
    event_store=InMemoryResponsesEventStore(),  # development only
)

Replace InMemoryResponsesEventStore before multi-replica or multi-tenant use. A production store must scope every read, write, and replay to the authenticated tenant and subject, coordinate concurrent writers, and enforce retention.

Hosting checklist

• Resolve client-facing aliases to server-owned agents and model policy.
• Authenticate every operation; protocol task, thread, response, session, and run IDs are not credentials.
• Derive dependencies, sessions, and idempotency keys from authenticated server state.
• Bound actual request bytes, field counts, prompt text, output, concurrency, and rate.
• Persist task/event state in a tenant-scoped durable store when multiple workers or replicas are possible.
• Redact prompts, tool arguments/results, artifacts, provider payloads, and exception details before export.
• Put approval authorization, expiry, one-time consumption, and audit in application code.

Start with agents and sessions or the Python quickstart, then apply the production architecture, stability rules, and troubleshooting guide before public hosting.

Python 0.24 durable application scaffold

The Beta zhivex init command now provides a durable application scaffold. Inspect zhivex init --help from the installed release for its options. The scaffold’s approval, restart, denial and cancellation paths have isolated-wheel acceptance coverage; deploying it still requires application-owned identity, authorization, persistence and recovery policy. See the Python agent guide.