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-5
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.