Agents SDK CLI Reference

The CLI ships as za - an umbrella command with four sub-apps: za agents (agent project management), za tools (custom tool authoring), za mcp (expose tools as an MCP server), and za platform (platform credentials).

Installation

pip install zetaalpha.agents

This installs both the za command and a legacy rag_agents alias. All documentation uses za agents.

Complete Command Tree

# Project Lifecycle
za agents init [DIR]                          # Scaffold config-first project
za agents dev [DIR]                           # Start Streamlit dev UI
za agents serve [DIR]                         # Start REST API server
za agents run "PROMPT"                        # Run agent headlessly
za agents perf server [DIR]                   # Run one crash-test API server
za agents perf client                         # TUI client: measure, kill, resume
za agents show                                # Project overview dashboard
za agents show [AGENT_ID]                     # Show agent config detail

# Agents (top-level CRUD)
za agents list                                # List all agents
za agents add [NAME] [--custom]               # Add agent (config-based or Python)
za agents remove [AGENT_ID]                   # Remove a custom agent
za agents configure [AGENT_ID]                # Re-configure an existing agent

# LLM Model
za agents model configure [MODEL]             # Interactive model + vendor setup
za agents model show                          # Show current model config
za agents model add [NAME]                    # Create a named LLM configuration
za agents model list                          # List named LLM configurations

# Capabilities (per-capability source management)
za agents capabilities <capability> [list|show|configure|settings|add]

# Policies (cross-cutting behavior)
za agents policies list                       # List policies and status
za agents policies show [POLICY]              # Show policy configuration
za agents policies configure [POLICY]         # Interactive policy setup

# Skills
za agents skill add [NAME] [--description]    # Create skill (agent-generated)
za agents skill list                          # List skill files
za agents skill remove [NAME]                 # Remove a skill

# Test Specs
za agents test run [SPECS_PATH]               # Run behavior spec tests
za agents test add [NAME] [--description]     # Create test spec
za agents test list                           # List test specs
za agents test remove [NAME]                  # Remove a test spec

# Deployment
za agents deploy list                         # List deployed projects
za agents deploy bundle [DIR]                 # Create deployment bundle
za agents deploy upload [DIR]                 # Upload bundle to platform
za agents deploy delete [PROJECT]             # Delete deployed project

# Custom Tools (no agent required)
za tools add [NAME]                           # Scaffold a custom tool source
za tools list                                 # List the project's tool sources
za tools remove [NAME]                        # Remove a tool source

# MCP Server (expose tools over MCP)
za mcp init [DIR] [--from-agent ID]           # Add an MCP exposure to a project
za mcp add [ID] [--from-agent ID|--tools SRC] # Add another named exposure
za mcp list                                   # List exposures
za mcp show [ID]                              # Show an exposure's configuration
za mcp remove [ID]                            # Remove an exposure
za mcp serve [DIR]                            # Serve /mcp (Streamable HTTP)
za mcp dev [DIR]                              # Serve + open the MCP Inspector
za mcp install [TARGET]                       # Wire a host: print | claude-desktop | cursor
za mcp add-tool [NAME]                        # Alias of `za tools add`

# Platform (credentials)
za platform login                             # Set platform credentials
za platform show                              # Show credentials (masked)
za platform reset                             # Reset to defaults

# Version
za version                                    # Print SDK version

Arguments in [brackets] are optional - if omitted, the CLI prompts interactively where supported. Project-scoped commands usually accept --project-dir; commands that modify a specific configured agent usually accept --agent. Run any command with --help for the exact flags.

Project Lifecycle Commands

za agents init

Scaffolds a new config-first agent project. Prompts for LLM vendor, model, API key, and capability toggles.

za agents init my-agents

Creates a working project with agent_setups.json, skills/, specs/, memories/, and env/.

za agents dev

Starts the Streamlit debugging UI for interactive agent testing.

za agents dev [DIR] [--reload] [--storage-backend disk|s3|azure] [--storage-path PATH]

• DIR: Project directory (defaults to current directory)
• --reload: Auto-reload on code changes
• --storage-backend: Where to save chat traces (disk, s3, azure)
• --storage-path: Path for traces on the selected backend

za agents serve

Starts the REST API server.

za agents serve [DIR] [--reload] [--host HOST]

• DIR: Project directory (defaults to current directory)
• --reload: Auto-reload on code changes
• --host: Host to listen on (default: localhost)

za agents run

Runs the agent headlessly with a single prompt. Prints the response to stdout.

za agents run "What is the latest research on transformers?"

za agents perf

Crash-tests resumable streaming across server processes. server runs one real REST API process with the file-backed persistence stores and a kill route for simulating an abrupt process death; client is a terminal UI that streams a turn, measures time-to-first-message and inter-message gaps, and drives the failure drills.

za agents perf server [DIR] [--port 8001] [--label server-1] [--storage-path .perf-storage] [--host 127.0.0.1] [--reload]
za agents perf client [--server name=url]... [--tenant TENANT] [--agent AGENT_ID] [--prompt "..."] [--message-id HANDLE]

• Start two or more servers on distinct ports with the same --storage-path: the shared directory is what lets a turn checkpointed by one server be resumed or followed by another.
• --server is repeatable (--server a=http://127.0.0.1:8001 --server b=http://127.0.0.1:8002); with no value the client targets two local servers on ports 8001 and 8002.
• In the client: s starts a turn, digits aim at a server, k kills the aimed server mid-turn, c drops the client view while the turn keeps running, r recovers (reattach, or resume from the last checkpoint when the producer is dead), y/p copy and paste a session_id:message_id handle to attach from another terminal, q quits.

za agents show

Shows a project overview dashboard: model, capabilities, skills, specs.

za agents show [DIR]

Agent Management

za agents list

Lists all agents in the project (built-in + custom).

za agents add

Adds a new agent to the project. By default, creates a config-based agent using the built-in agent. Use --custom to generate a Python agent class.

za agents add                    # config-based agent (recommended)
za agents add --custom           # custom Python agent class

za agents remove

Removes a custom agent from the project.

za agents remove [AGENT_ID]

za agents configure

Re-configures an existing agent interactively (LLM, capabilities, tenant).

za agents configure [AGENT_ID]

Model Configuration

za agents model configure

Interactive model and vendor setup. Auto-detects vendor from model name.

za agents model configure claude-sonnet-4-6

za agents model show

Shows the current model, vendor, and parameters.

za agents model add

Creates a named LLM configuration in llm_configurations.json; the credential goes to env/secrets.json (see Secrets). Agents reference it via llm_configuration_name - see the Configuration Reference.

za agents model add default

za agents model list

Lists the project's named LLM configurations (name, vendor, model).

Capabilities

The capabilities command manages the agent's capability sources. Each capability has its own CLI name:

Capability	CLI name
Tools	tool-sets
Skills	skill-sources
Memory	memory-stores
Context	context-sources
Instructions	instruction-sources
Delegation	delegation-sources
Processing	processors
Dispatch	dispatch-rules
MCP	mcp-servers

Per-capability subcommands

za agents capabilities <capability>             # Capability overview
za agents capabilities <capability> list        # List sources + active/inactive
za agents capabilities <capability> show [SRC]  # Show source config
za agents capabilities <capability> configure [SRC]  # Interactive source config
za agents capabilities <capability> settings    # Capability-level settings
za agents capabilities <capability> add [NAME]  # Scaffold custom source

MCP-specific subcommands

za agents capabilities mcp-servers add [NAME] [--transport T] [--url URL] [--command COMMAND]
za agents capabilities mcp-servers list
za agents capabilities mcp-servers show [NAME]
za agents capabilities mcp-servers remove [NAME]
za agents capabilities mcp-servers settings

Policies

The policies command manages cross-cutting agent behaviors that apply on top of capabilities.

Policy	Description
citations	Controls how the agent formats and includes citations in responses

za agents policies list

Lists all available policies and whether they are active for the current agent.

za agents policies show

Shows the configuration fields and current values for a policy.

za agents policies show citations

za agents policies configure

Interactively configures a policy.

za agents policies configure citations

Skills

za agents skill add

Creates a new skill. When an LLM is configured, uses the agent to generate the skill content from the description.

za agents skill add patent-analysis --description "Help users analyze patent claims"
za agents skill add patent-analysis --no-generate   # empty template

za agents skill list

Lists all skill directories in skills/.

za agents skill remove

Removes a skill directory.

Test Specs

za agents test run

Runs behavior spec tests.

za agents test run [SPECS_PATH] [--pattern "*.yaml"]

za agents test add

Creates a new test spec. Supports --description for agent-generated content.

za agents test add greeting-test --description "Verify the agent introduces itself"

za agents test list / za agents test remove

List or remove test spec files.

Deployment

za agents deploy upload

Bundles and uploads the project to the platform. Runs validation before uploading. After a successful upload, outputs an agent setup JSON file for each agent in build/. These files contain the bot_identifier, agent_name, and bot_configuration — use them to fill in the agent form fields in Platform Admin.

za agents deploy upload [DIR]

za agents deploy bundle

Creates a deployment bundle (build.zip) without uploading. Also outputs agent setup JSON files per agent in build/.

za agents deploy delete

Deletes a deployed project from the platform. Prompts for confirmation before deleting.

za agents deploy delete [PROJECT]

• PROJECT: The project name to delete (defaults to current directory name)

za agents deploy list

Lists deployed projects on the platform.

Custom Tools (za tools)

Author tool sources without creating an agent first. A tool source created here is available to both agents and MCP exposures in the same project.

za tools add

Scaffolds a custom tool source under dependencies/ (creates the project skeleton if needed).

za tools add currency-converter

za tools list / za tools remove

List the project's tool sources, or remove one (deletes the file and its registration).

MCP Server (za mcp)

Expose a project's tools as an MCP server (Streamable HTTP). Exposures live in mcp_setups.json: each entry has an mcp_server_identifier and a configuration of tool-source blocks - the same blocks as agent_configuration. See How to Serve Tools over MCP.

za mcp init

Adds a default exposure to a project (scaffolds the skeleton if needed), seeded from the project's default agent, from --from-agent, or a starter tool bundle.

za mcp init my-agents --from-agent rag

za mcp add / za mcp list / za mcp show / za mcp remove

Manage additional named exposures. --from-agent copies an agent's tool configuration; --tools web_tools,index_tools enables specific sources.

za mcp serve

Serves the project at http://127.0.0.1:8000/mcp/zetaalpha/?mcp_server_identifier=<id>. --reload for auto-reload.

za mcp serve .

za mcp dev

Same as serve, plus launches the MCP Inspector (npx @modelcontextprotocol/inspector) for interactive testing.

za mcp install

Prints or writes the mcpServers config for a host: print (default), claude-desktop, or cursor. --remote --tenant <tenant> points at the hosted Zeta Alpha MCP server instead of the local one.

za mcp install claude-desktop
za mcp install print --remote --tenant my-tenant

Platform Credentials

za platform login

Logs in to a tenant (base URL, API key, tenant). Interactive or with flags. One login is kept per tenant; the latest becomes the current one. When the project runs, an agent whose agent_configuration.tenant has a login gets that login's key; every other agent gets the current one.

za platform login
za platform login --base-url https://api.zeta-alpha.com --api-key sk-... --tenant my-tenant

za platform use

Makes a saved login the current one.

za platform use my-tenant

za platform show

Shows the current login and the other saved logins (API keys masked).

za platform reset

Resets credentials to defaults.

Version

za version

Legacy Compatibility

The rag_agents entry point remains as a deprecated alias pointing to the agents sub-app. Existing scripts using rag_agents serve, rag_agents dev, etc. continue to work.