Moss Agent CLI

Command-line tool for deploying voice agents to the Moss platform.

Installation

pip install moss-agent-cli

Or install from source:

cd moss-agent-cli
pip install -e .

Usage

Deploy Command

Deploy your agent to the Moss platform:

moss-agent deploy

Push Env Vars

Upload your agent's runtime env vars from a local file. Secrets aren't packaged with the code — push them separately:

moss-agent env push                       # uses ./.env
moss-agent env push --env-file .env.prod  # custom file

Pushing restarts the deployed agent. Requires a prior successful moss-agent deploy.

Required Environment Variables

Set these environment variables or pass as CLI options:

export MOSS_PROJECT_ID="your-project-id"
export MOSS_PROJECT_KEY="your-project-key"
export MOSS_VOICE_AGENT_ID="your-voice-agent-id"

Or pass as options:

moss-agent deploy \
  --project-id "your-project-id" \
  --project-key "your-project-key" \
  --voice-agent-id "your-voice-agent-id"

Agent Structure

Your agent directory must contain an entry point file that imports from moss_voice_agent_manager:

Simple structure:

my-agent/
├── agent.py              # Entry point (uses MossAgentSession)
├── requirements.txt      # Optional: Additional dependencies
└── tools/               # Optional: Custom tools
    └── my_tools.py

Or with main.py:

my-agent/
├── main.py              # Entry point
├── requirements.txt
└── ...

Or with src structure:

my-agent/
├── src/
│   └── my_agent/
│       └── main.py      # Entry point
├── requirements.txt
└── ...

Example agent.py

from moss_voice_agent_manager import MossAgentSession

def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city} is sunny"

session = MossAgentSession(
    function_tools=[get_weather],
    max_tool_steps=10,
)

if __name__ == "__main__":
    session.run()

CLI Options

moss-agent deploy [OPTIONS] [DIRECTORY]

Arguments:
  DIRECTORY                Agent directory to deploy (defaults to current directory)

Options:
  --project-id, -p TEXT    Moss project ID (or set MOSS_PROJECT_ID env var)
  --project-key, -k TEXT   Moss project key (or set MOSS_PROJECT_KEY env var)
  --voice-agent-id, -v TEXT Voice agent ID (or set MOSS_VOICE_AGENT_ID env var)
  --api-url TEXT          Moss platform API URL (defaults to production)
  --help                  Show this message and exit

moss-agent env push [OPTIONS] [DIRECTORY]

Arguments:
  DIRECTORY                Agent directory (defaults to current directory)

Options:
  --env-file, -f PATH      Path to env file with KEY=VALUE pairs (default: .env)
  --project-id, -p TEXT    Moss project ID (or set MOSS_PROJECT_ID env var)
  --project-key, -k TEXT   Moss project key (or set MOSS_PROJECT_KEY env var)
  --voice-agent-id, -v TEXT Voice agent ID (or set MOSS_VOICE_AGENT_ID env var)
  --api-url TEXT          Moss platform API URL (defaults to production)
  --overwrite / --no-overwrite  Overwrite existing secrets (default: enabled)
  --ignore-empty          Skip env vars with empty values instead of failing
  --help                  Show this message and exit

What Gets Deployed

When you run moss-agent deploy, the CLI:

1. Validates your agent structure
2. Packages your agent directory (excluding .env, pycache, .git, etc.)
3. Uploads the package to Moss platform
4. Deploys to LiveKit Cloud

Your agent code is deployed as-is - no modification or generation.

Excluded Files

The following files/directories are automatically excluded from deployment:

• .env - Environment variables (secrets) — push these separately with moss-agent env push
• __pycache__/ - Python cache
• .git/ - Git repository
• *.pyc - Compiled Python files
• .venv/, venv/ - Virtual environments
• .DS_Store - macOS metadata

Development

Install in development mode:

cd moss-agent-cli
pip install -e .

Run the CLI:

moss-agent deploy

License

MIT