Agents SDK CLI Reference
The CLI ships as za - an umbrella command with two sub-apps: za agents (agent project management) 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 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
# 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
# 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 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.
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.
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.