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.

Optional features ship as extras, installed with pip install 'zetaalpha.agents[EXTRA]':

ExtraEnables
openai, azure-openai, anthropic, azure-anthropic, bedrock-anthropic, bedrock-converseLLM vendor clients
langchain, langchain-openai, langchain-anthropic, langchain-awsLangChain integration
mcpMCP servers (consume and expose)
replPython REPL sandbox (Python 3.10+)
realtimeRealtime transcription
web_tools, sql_tools, dataframe_toolsWeb, SQL and dataframe tool sets
langfuseLangfuse tracing
cliCLI dependencies: Typer, the Streamlit dev UI and evaluation
allEvery extra above

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 use TENANT                        # Switch to a saved login
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, llm_configurations.json, env/secrets.json, skills/, instructions/, specs/ and memories/. Later steps add mcp_configurations.json (za agents capabilities mcp-servers add), mcp_setups.json (za mcp init), env/zav_config.json (za platform login), and realtime_transcription_setup.json, which you write by hand (see Realtime Transcription).

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

The model type prompt accepts chat, responses (reasoning models with tools) and image (image generation models, used through the image generation tools; the default for gpt-image-2.5* names).

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
Interjectionsinterjection-sources
Python REPLrepl-sandboxes
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] [--description TEXT] [--header-secret HEADER=SECRET]
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
za agents capabilities mcp-servers explore [NAME] [--url URL|--command COMMAND] [--call TOOL] [--args JSON]
za agents capabilities mcp-servers connect NAME
  • add writes the server to mcp_configurations.json and mounts it on the agent. --transport defaults to stdio. --description is what the agent reads about the server. --header-secret (repeatable) sends HEADER with the value of SECRET from env/secrets.json.
  • explore connects to a configured server, or an ad-hoc one given by --url or --command, and lists its tools; --call invokes one with the JSON --args.
  • connect connects a configured server for the local user and stores its tools, as the chat's connect action does, so za agents serve serves them without connecting.

All MCP subcommands except connect accept --project-dir and --agent; connect accepts --project-dir.

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 (citation_configuration)
modelSelects a named LLM configuration for the request (llm_selection_configuration)

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.