Skip to main content

multi-agent-cli

PyPI CI codecov Python 3.11+ License: MIT

Command-line tool for orchestrating multiple AI agents in parallel or sequence. Think "kubectl for AI agents."

Features

  • Single Agent Execution: Run one agent with specific action and parameters
  • Parallel Orchestration: Run multiple agents simultaneously with rate limiting
  • Sequential Workflows: Chain agent operations with data flow between steps
  • Rich Terminal Output: Beautiful progress bars, tables, and status indicators
  • Prometheus Metrics: Production-ready observability and monitoring
  • 100% Test Coverage: Thoroughly tested and reliable

Quick Start

# Install
pip install multi-agent-cli

# Initialize configuration
multi-agent-cli init

# Run single agent
multi-agent-cli run pm track_tasks --path ./src

# Run parallel analysis
multi-agent-cli parallel --agents pm,research,index --path ./src

# Execute workflow
multi-agent-cli workflow code-review.yaml

Installation

# From PyPI
pip install multi-agent-cli

# From source
git clone https://github.com/kmcallorum/multi-agent-cli.git
cd multi-agent-cli
pip install -e ".[dev]"

Requirements

  • Python 3.11+
  • pytest-agents 1.0.0+

Usage

Running a Single Agent

# Basic usage
multi-agent-cli run AGENT ACTION [OPTIONS]

# Examples
multi-agent-cli run pm track_tasks --path ./src
multi-agent-cli run research analyze_document --path README.md
multi-agent-cli run index index_repository --path ./src

# With JSON parameters
multi-agent-cli run pm track_tasks --params '{"include_done": true}'

# Save output to file
multi-agent-cli run pm track_tasks --output results.json

Parallel Execution

# Run multiple agents in parallel
multi-agent-cli parallel --agents pm,research,index --path ./src

# Limit parallel workers
multi-agent-cli parallel --agents pm,research,index --max-workers 2

# Save aggregated results
multi-agent-cli parallel --agents pm,research --output parallel_results.json

Workflow Execution

# Run a workflow file
multi-agent-cli workflow code-review.yaml

# Strict mode (fail on first error)
multi-agent-cli workflow compliance-check.yaml --strict

# Continue on errors
multi-agent-cli workflow analysis.yaml --continue-on-error

Configuration Management

# Show current configuration
multi-agent-cli config show

# Validate configuration file
multi-agent-cli config validate agents.yaml

# Initialize with example workflows
multi-agent-cli config init --example-workflows

Metrics Server

# Start Prometheus metrics server
multi-agent-cli metrics --port 9090

# Access metrics at http://localhost:9090/metrics

Configuration

agents.yaml

agents:
  pm:
    enabled: true
    path: "./pm/dist/index.js"
    timeout: 60

  research:
    enabled: true
    path: "./research/dist/index.js"
    timeout: 90

  index:
    enabled: true
    path: "./index/dist/index.js"
    timeout: 120

settings:
  max_parallel_workers: 3
  default_timeout: 60
  metrics_enabled: true
  metrics_port: 9090

output:
  format: "rich"
  verbose: false
  save_results: true
  results_dir: "./results"

Workflow Definition

name: "Code Quality Analysis"
description: "Comprehensive code quality check"

steps:
  - name: "Track Technical Debt"
    agent: pm
    action: track_tasks
    params:
      path: "./src"
    on_error: continue

  - name: "Analyze Documentation"
    agent: research
    action: analyze_document
    params:
      path: "./README.md"
    on_error: fail

  - name: "Index Codebase"
    agent: index
    action: index_repository
    params:
      path: "./src"
    depends_on:
      - "Track Technical Debt"

quality_gates:
  max_fixmes: 5
  min_documentation_score: 0.8
  max_dead_code_percent: 5

Output Formats

# Rich terminal output (default)
multi-agent-cli run pm track_tasks

# JSON output
multi-agent-cli --format json run pm track_tasks

# Table output
multi-agent-cli --format table run pm track_tasks

Docker

# Build image
docker build -t multi-agent-cli .

# Run single agent
docker run -v $(pwd)/src:/workspace/src multi-agent-cli run pm track_tasks

# Run with docker-compose
docker-compose up multi-agent-cli

Development

# Clone repository
git clone https://github.com/kmcallorum/multi-agent-cli.git
cd multi-agent-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/multi_agent_cli --cov-report=term-missing

# Lint
ruff check src tests
ruff format src tests

# Type check
mypy src

Metrics

The CLI exposes Prometheus metrics when using the metrics command:

  • agent_invocations_total - Total agent invocations by agent/action
  • agent_invocations_success_total - Successful invocations
  • agent_invocations_error_total - Failed invocations
  • agent_duration_seconds - Execution duration histogram
  • workflows_executed_total - Total workflows executed
  • workflows_success_total - Successful workflows
  • parallel_executions_total - Total parallel executions
  • cli_commands_total - CLI commands executed

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for security policy and reporting vulnerabilities.

License

MIT License - see LICENSE for details.

Metadata

Release files for multi-agent-cli 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for multi-agent-cli 1.1.0
File Size Uploaded Provenance Actions
multi_agent_cli-1.1.0.tar.gz 54.8 kB Without provenance Details for multi_agent_cli-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for multi-agent-cli 1.1.0
File Interpreter ABI Platform Actions
multi_agent_cli-1.1.0-py3-none-any.whl Python 3 none any Details for multi_agent_cli-1.1.0-py3-none-any.whl

Total release size: 80.5 kB

Release files / multi_agent_cli-1.1.0.tar.gz

Download URL multi_agent_cli-1.1.0.tar.gz
Size 54.8 kB
Tags Source
SHA-256 checksum
How to use checksums
76db83369082fe931a545e439f67ae50bfbd26ac952c3428f1fb678a98f4325e
BLAKE2b-256 checksum
How to use checksums
209934fd032ead9b0b12496467b1a44d8c4d3b39c2378a33959da8295dab99bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.14

Release files / multi_agent_cli-1.1.0-py3-none-any.whl

Download URL multi_agent_cli-1.1.0-py3-none-any.whl
Size 25.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2125fa869e7fb9818c2281d2ebbd04171cb3ece7f29a1515b511fdc46a2e29fa
BLAKE2b-256 checksum
How to use checksums
1c2beabb3eb1b8936ff277cdf19c8984efeb6b513637e61ddc3d6e5058130237
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.14

Security for multi-agent-cli 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page