Skip to main content

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 (credentials go to env/llm_configurations.json). 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:

CapabilityCLI name
Toolstool-sets
Skillsskill-sources
Memorymemory-stores
Contextcontext-sources
Instructionsinstruction-sources
Delegationdelegation-sources
Processingprocessors
Dispatchdispatch-rules
MCPmcp-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.

PolicyDescription
citationsControls 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​

Sets platform credentials (base URL, API key, tenant). Interactive or with flags.

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

za platform show​

Shows current credentials (API key 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.