Kye Gomez
2 weeks ago
parent
e5ce99fd0a
commit
0930a17512
@ -0,0 +1,615 @@
|
||||
# Swarms CLI Examples
|
||||
|
||||
This document provides comprehensive examples of how to use the Swarms CLI for various scenarios. Each example includes the complete command, expected output, and explanation.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Basic Usage Examples](#basic-usage-examples)
|
||||
- [Agent Management Examples](#agent-management-examples)
|
||||
- [Multi-Agent Workflow Examples](#multi-agent-workflow-examples)
|
||||
- [Configuration Examples](#configuration-examples)
|
||||
- [Advanced Usage Examples](#advanced-usage-examples)
|
||||
- [Troubleshooting Examples](#troubleshooting-examples)
|
||||
|
||||
## Basic Usage Examples
|
||||
|
||||
### 1. Getting Started
|
||||
|
||||
#### Check CLI Installation
|
||||
|
||||
```bash
|
||||
swarms help
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
_________
|
||||
/ _____/_ _ _______ _______ _____ ______
|
||||
\_____ \\ \/ \/ /\__ \\_ __ \/ \ / ___/
|
||||
/ \\ / / __ \| | \/ Y Y \\___ \
|
||||
/_______ / \/\_/ (____ /__| |__|_| /____ >
|
||||
\/ \/ \/ \/
|
||||
|
||||
Available Commands
|
||||
┌─────────────────┬─────────────────────────────────────────────────────────────┐
|
||||
│ Command │ Description │
|
||||
├─────────────────┼─────────────────────────────────────────────────────────────┤
|
||||
│ onboarding │ Start the interactive onboarding process │
|
||||
│ help │ Display this help message │
|
||||
│ get-api-key │ Retrieve your API key from the platform │
|
||||
│ check-login │ Verify login status and initialize cache │
|
||||
│ run-agents │ Execute agents from your YAML configuration │
|
||||
│ load-markdown │ Load agents from markdown files with YAML frontmatter │
|
||||
│ agent │ Create and run a custom agent with specified parameters │
|
||||
│ auto-upgrade │ Update Swarms to the latest version │
|
||||
│ book-call │ Schedule a strategy session with our team │
|
||||
│ autoswarm │ Generate and execute an autonomous swarm │
|
||||
└─────────────────┴─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Start Onboarding Process
|
||||
```bash
|
||||
swarms onboarding
|
||||
```
|
||||
|
||||
This will start an interactive setup process to configure your environment.
|
||||
|
||||
#### Get API Key
|
||||
|
||||
```bash
|
||||
swarms get-api-key
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✓ API key page opened in your browser
|
||||
```
|
||||
|
||||
#### Check Login Status
|
||||
|
||||
```bash
|
||||
swarms check-login
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
✓ Authentication verified
|
||||
```
|
||||
|
||||
## Agent Management Examples
|
||||
|
||||
### 2. Creating Custom Agents
|
||||
|
||||
#### Basic Research Agent
|
||||
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Research Assistant" \
|
||||
--description "AI research specialist for academic papers" \
|
||||
--system-prompt "You are an expert research assistant specializing in academic research. You help users find, analyze, and synthesize information from various sources. Always provide well-structured, evidence-based responses." \
|
||||
--task "Research the latest developments in quantum computing and provide a summary of key breakthroughs in the last 2 years" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.1 \
|
||||
--max-loops 3
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Creating custom agent: Research Assistant
|
||||
[✓] Agent 'Research Assistant' completed the task successfully!
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Agent Execution Results │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Agent Name: Research Assistant │
|
||||
│ Model: gpt-4 │
|
||||
│ Task: Research the latest developments in quantum computing... │
|
||||
│ Result: │
|
||||
│ Recent breakthroughs in quantum computing include: │
|
||||
│ 1. Google's 53-qubit Sycamore processor achieving quantum supremacy │
|
||||
│ 2. IBM's 433-qubit Osprey processor... │
|
||||
│ ... │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Code Review Agent
|
||||
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Code Reviewer" \
|
||||
--description "Expert code review assistant with security focus" \
|
||||
--system-prompt "You are a senior software engineer specializing in code review, security analysis, and best practices. Review code for bugs, security vulnerabilities, performance issues, and adherence to coding standards." \
|
||||
--task "Review this Python code for security vulnerabilities and suggest improvements: def process_user_input(data): return eval(data)" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.05 \
|
||||
--max-loops 2 \
|
||||
--verbose
|
||||
```
|
||||
|
||||
#### Financial Analysis Agent
|
||||
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Financial Analyst" \
|
||||
--description "Expert financial analyst for market research and investment advice" \
|
||||
--system-prompt "You are a certified financial analyst with expertise in market analysis, investment strategies, and risk assessment. Provide data-driven insights and recommendations based on current market conditions." \
|
||||
--task "Analyze the current state of the technology sector and provide investment recommendations for the next quarter" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.2 \
|
||||
--max-loops 2 \
|
||||
--output-type "json"
|
||||
```
|
||||
|
||||
### 3. Advanced Agent Configuration
|
||||
|
||||
#### Agent with Dynamic Features
|
||||
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Adaptive Writer" \
|
||||
--description "Content writer with dynamic temperature and context adjustment" \
|
||||
--system-prompt "You are a professional content writer who adapts writing style based on audience and context. You can write in various tones from formal to casual, and adjust complexity based on the target audience." \
|
||||
--task "Write a blog post about artificial intelligence for a general audience, explaining complex concepts in simple terms" \
|
||||
--model-name "gpt-4" \
|
||||
--dynamic-temperature-enabled \
|
||||
--dynamic-context-window \
|
||||
--context-length 8000 \
|
||||
--retry-attempts 3 \
|
||||
--return-step-meta \
|
||||
--autosave \
|
||||
--saved-state-path "./agent_states/"
|
||||
```
|
||||
|
||||
#### Agent with MCP Integration
|
||||
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "MCP Agent" \
|
||||
--description "Agent with Model Context Protocol integration" \
|
||||
--system-prompt "You are a agent with access to external tools and data sources through MCP. Use these capabilities to provide comprehensive and up-to-date information." \
|
||||
--task "Search for recent news about climate change and summarize the key findings" \
|
||||
--model-name "gpt-4" \
|
||||
--mcp-url "https://api.example.com/mcp" \
|
||||
--temperature 0.1 \
|
||||
--max-loops 5
|
||||
```
|
||||
|
||||
## Multi-Agent Workflow Examples
|
||||
|
||||
### 4. Running Agents from YAML Configuration
|
||||
|
||||
#### Create `research_team.yaml`
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
- name: "Data Collector"
|
||||
description: "Specialist in gathering and organizing data from various sources"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a data collection specialist. Your role is to gather relevant information from multiple sources and organize it in a structured format."
|
||||
temperature: 0.1
|
||||
max_loops: 3
|
||||
|
||||
- name: "Data Analyzer"
|
||||
description: "Expert in analyzing and interpreting complex datasets"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a data analyst. Take the collected data and perform comprehensive analysis to identify patterns, trends, and insights."
|
||||
temperature: 0.2
|
||||
max_loops: 4
|
||||
|
||||
- name: "Report Writer"
|
||||
description: "Professional writer who creates clear, compelling reports"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a report writer. Take the analyzed data and create a comprehensive, well-structured report that communicates findings clearly."
|
||||
temperature: 0.3
|
||||
max_loops: 3
|
||||
```
|
||||
|
||||
#### Execute the Team
|
||||
|
||||
```bash
|
||||
swarms run-agents --yaml-file research_team.yaml
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Loading agents from research_team.yaml...
|
||||
[✓] Agents completed their tasks successfully!
|
||||
|
||||
Results:
|
||||
Data Collector: [Collected data from 15 sources...]
|
||||
Data Analyzer: [Identified 3 key trends and 5 significant patterns...]
|
||||
Report Writer: [Generated comprehensive 25-page report...]
|
||||
```
|
||||
|
||||
### 5. Loading Agents from Markdown
|
||||
|
||||
#### Create `agents/researcher.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Market Researcher
|
||||
description: Expert in market research and competitive analysis
|
||||
model_name: gpt-4
|
||||
temperature: 0.1
|
||||
max_loops: 3
|
||||
---
|
||||
|
||||
You are an expert market researcher with 15+ years of experience in competitive analysis, market sizing, and trend identification. You specialize in technology markets and have deep knowledge of consumer behavior, pricing strategies, and market dynamics.
|
||||
|
||||
Your approach includes:
|
||||
- Systematic data collection from multiple sources
|
||||
- Quantitative and qualitative analysis
|
||||
- Competitive landscape mapping
|
||||
- Market opportunity identification
|
||||
- Risk assessment and mitigation strategies
|
||||
```
|
||||
|
||||
#### Create `agents/analyst.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Business Analyst
|
||||
description: Strategic business analyst focusing on growth opportunities
|
||||
model_name: gpt-4
|
||||
temperature: 0.2
|
||||
max_loops: 4
|
||||
---
|
||||
|
||||
You are a senior business analyst specializing in strategic planning and growth strategy. You excel at identifying market opportunities, analyzing competitive advantages, and developing actionable business recommendations.
|
||||
|
||||
Your expertise covers:
|
||||
- Market opportunity analysis
|
||||
- Competitive positioning
|
||||
- Business model innovation
|
||||
- Risk assessment
|
||||
- Strategic planning frameworks
|
||||
```
|
||||
|
||||
#### Load and Use Agents
|
||||
|
||||
```bash
|
||||
swarms load-markdown --markdown-path ./agents/ --concurrent
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
Loading agents from markdown: ./agents/
|
||||
✓ Successfully loaded 2 agents!
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Loaded Agents │
|
||||
├─────────────────┬──────────────┬───────────────────────────────────────────┤
|
||||
│ Name │ Model │ Description │
|
||||
├─────────────────┼──────────────┼───────────────────────────────────────────┤
|
||||
│ Market Researcher│ gpt-4 │ Expert in market research and competitive │
|
||||
│ │ │ analysis │
|
||||
├─────────────────┼──────────────┼───────────────────────────────────────────┤
|
||||
│ Business Analyst│ gpt-4 │ Strategic business analyst focusing on │
|
||||
│ │ │ growth opportunities │
|
||||
└─────────────────┴──────────────┴───────────────────────────────────────────┘
|
||||
|
||||
Ready to use 2 agents!
|
||||
You can now use these agents in your code or run them interactively.
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### 6. YAML Configuration Templates
|
||||
|
||||
#### Simple Agent Configuration
|
||||
|
||||
```yaml
|
||||
# simple_agent.yaml
|
||||
agents:
|
||||
- name: "Simple Assistant"
|
||||
description: "Basic AI assistant for general tasks"
|
||||
model_name: "gpt-3.5-turbo"
|
||||
system_prompt: "You are a helpful AI assistant."
|
||||
temperature: 0.7
|
||||
max_loops: 1
|
||||
```
|
||||
|
||||
#### Advanced Multi-Agent Configuration
|
||||
|
||||
```yaml
|
||||
# advanced_team.yaml
|
||||
agents:
|
||||
- name: "Project Manager"
|
||||
description: "Coordinates team activities and ensures project success"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a senior project manager with expertise in agile methodologies, risk management, and team coordination."
|
||||
temperature: 0.1
|
||||
max_loops: 5
|
||||
auto_generate_prompt: true
|
||||
dynamic_temperature_enabled: true
|
||||
|
||||
- name: "Technical Lead"
|
||||
description: "Provides technical guidance and architecture decisions"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a technical lead with deep expertise in software architecture, system design, and technical decision-making."
|
||||
temperature: 0.2
|
||||
max_loops: 4
|
||||
context_length: 12000
|
||||
retry_attempts: 3
|
||||
|
||||
- name: "Quality Assurance"
|
||||
description: "Ensures quality standards and testing coverage"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a QA specialist focused on quality assurance, testing strategies, and process improvement."
|
||||
temperature: 0.1
|
||||
max_loops: 3
|
||||
return_step_meta: true
|
||||
dashboard: true
|
||||
```
|
||||
|
||||
### 7. Markdown Configuration Templates
|
||||
|
||||
#### Research Agent Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Research Specialist
|
||||
description: Academic research and literature review expert
|
||||
model_name: gpt-4
|
||||
temperature: 0.1
|
||||
max_loops: 5
|
||||
context_length: 16000
|
||||
auto_generate_prompt: true
|
||||
---
|
||||
|
||||
You are a research specialist with expertise in academic research methodologies, literature review, and scholarly writing. You excel at:
|
||||
|
||||
- Systematic literature reviews
|
||||
- Research methodology design
|
||||
- Data analysis and interpretation
|
||||
- Academic writing and citation
|
||||
- Research gap identification
|
||||
|
||||
Always provide evidence-based responses and cite relevant sources when possible.
|
||||
```
|
||||
|
||||
#### Creative Writing Agent Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Creative Writer
|
||||
description: Professional creative writer and storyteller
|
||||
model_name: gpt-4
|
||||
temperature: 0.8
|
||||
max_loops: 3
|
||||
dynamic_temperature_enabled: true
|
||||
output_type: markdown
|
||||
---
|
||||
|
||||
You are a creative writer with a passion for storytelling, character development, and engaging narratives. You specialize in:
|
||||
|
||||
- Fiction writing across multiple genres
|
||||
- Character development and dialogue
|
||||
- Plot structure and pacing
|
||||
- Creative problem-solving
|
||||
- Engaging opening hooks and satisfying conclusions
|
||||
|
||||
Your writing style is adaptable, engaging, and always focused on creating memorable experiences for readers.
|
||||
```
|
||||
|
||||
## Advanced Usage Examples
|
||||
|
||||
### 8. Autonomous Swarm Generation
|
||||
|
||||
#### Simple Task
|
||||
```bash
|
||||
swarms autoswarm \
|
||||
--task "Create a weekly meal plan for a family of 4 with dietary restrictions" \
|
||||
--model "gpt-4"
|
||||
```
|
||||
|
||||
#### Complex Research Task
|
||||
```bash
|
||||
swarms autoswarm \
|
||||
--task "Conduct a comprehensive analysis of the impact of artificial intelligence on job markets, including historical trends, current state, and future projections. Include case studies from different industries and recommendations for workforce adaptation." \
|
||||
--model "gpt-4"
|
||||
```
|
||||
|
||||
### 9. Integration Examples
|
||||
|
||||
#### CI/CD Pipeline Integration
|
||||
```yaml
|
||||
# .github/workflows/swarms-test.yml
|
||||
name: Swarms Agent Testing
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test-agents:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.9'
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install swarms
|
||||
- name: Run Swarms Agents
|
||||
run: |
|
||||
swarms run-agents --yaml-file ci_agents.yaml
|
||||
env:
|
||||
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
||||
```
|
||||
|
||||
#### Shell Script Integration
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# run_daily_analysis.sh
|
||||
|
||||
echo "Starting daily market analysis..."
|
||||
|
||||
# Run market research agent
|
||||
swarms agent \
|
||||
--name "Daily Market Analyzer" \
|
||||
--description "Daily market analysis and reporting" \
|
||||
--system-prompt "You are a market analyst providing daily market insights." \
|
||||
--task "Analyze today's market movements and provide key insights" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.1
|
||||
|
||||
# Run risk assessment agent
|
||||
swarms agent \
|
||||
--name "Risk Assessor" \
|
||||
--description "Risk assessment and mitigation specialist" \
|
||||
--system-prompt "You are a risk management expert." \
|
||||
--task "Assess current market risks and suggest mitigation strategies" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.2
|
||||
|
||||
echo "Daily analysis complete!"
|
||||
```
|
||||
|
||||
## Troubleshooting Examples
|
||||
|
||||
### 10. Common Error Scenarios
|
||||
|
||||
#### Missing API Key
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Test Agent" \
|
||||
--description "Test" \
|
||||
--system-prompt "Test" \
|
||||
--task "Test"
|
||||
```
|
||||
|
||||
**Expected Error:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Failed to create or run agent: No API key found │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Please check:
|
||||
1. Your API keys are set correctly
|
||||
2. The model name is valid
|
||||
3. All required parameters are provided
|
||||
4. Your system prompt is properly formatted
|
||||
```
|
||||
|
||||
**Resolution:**
|
||||
```bash
|
||||
export OPENAI_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
#### Invalid YAML Configuration
|
||||
```bash
|
||||
swarms run-agents --yaml-file invalid.yaml
|
||||
```
|
||||
|
||||
**Expected Error:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┘
|
||||
│ Configuration Error │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Error parsing YAML: Invalid YAML syntax │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Please check your agents.yaml file format.
|
||||
```
|
||||
|
||||
#### File Not Found
|
||||
```bash
|
||||
swarms load-markdown --markdown-path ./nonexistent/
|
||||
```
|
||||
|
||||
**Expected Error:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ File Error │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Markdown file/directory not found: ./nonexistent/ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Please make sure the path exists and you're in the correct directory.
|
||||
```
|
||||
|
||||
### 11. Debug Mode Usage
|
||||
|
||||
#### Enable Verbose Output
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Debug Agent" \
|
||||
--description "Agent for debugging" \
|
||||
--system-prompt "You are a debugging assistant." \
|
||||
--task "Help debug this issue" \
|
||||
--model-name "gpt-4" \
|
||||
--verbose
|
||||
```
|
||||
|
||||
This will provide detailed output including:
|
||||
- Step-by-step execution details
|
||||
- API call information
|
||||
- Internal state changes
|
||||
- Performance metrics
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 12. Performance Optimization
|
||||
|
||||
#### Use Concurrent Processing
|
||||
```bash
|
||||
# For multiple markdown files
|
||||
swarms load-markdown \
|
||||
--markdown-path ./large_agent_directory/ \
|
||||
--concurrent
|
||||
```
|
||||
|
||||
#### Optimize Model Selection
|
||||
```bash
|
||||
# For simple tasks
|
||||
--model-name "gpt-3.5-turbo" --temperature 0.1
|
||||
|
||||
# For complex reasoning
|
||||
--model-name "gpt-4" --temperature 0.1 --max-loops 5
|
||||
```
|
||||
|
||||
#### Context Length Management
|
||||
```bash
|
||||
# For long documents
|
||||
--context-length 16000 --dynamic-context-window
|
||||
|
||||
# For concise responses
|
||||
--context-length 4000 --max-loops 2
|
||||
```
|
||||
|
||||
### 13. Security Considerations
|
||||
|
||||
#### Environment Variable Usage
|
||||
```bash
|
||||
# Secure API key management
|
||||
export OPENAI_API_KEY="your-secure-key"
|
||||
export ANTHROPIC_API_KEY="your-secure-key"
|
||||
|
||||
# Use in CLI
|
||||
swarms agent [options]
|
||||
```
|
||||
|
||||
#### File Permissions
|
||||
```bash
|
||||
# Secure configuration files
|
||||
chmod 600 agents.yaml
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
The Swarms CLI provides a powerful and flexible interface for managing AI agents and multi-agent workflows. These examples demonstrate:
|
||||
|
||||
| Feature | Description |
|
||||
|------------------------|---------------------------------------------------------|
|
||||
| **Basic Usage** | Getting started with the CLI |
|
||||
| **Agent Management** | Creating and configuring custom agents |
|
||||
| **Multi-Agent Workflows** | Coordinating multiple agents |
|
||||
| **Configuration** | YAML and markdown configuration formats |
|
||||
| **Advanced Features** | Dynamic configuration and MCP integration |
|
||||
| **Troubleshooting** | Common issues and solutions |
|
||||
| **Best Practices** | Performance and security considerations |
|
||||
|
||||
For more information, refer to the [CLI Reference](cli_reference.md) documentation.
|
||||
@ -0,0 +1,419 @@
|
||||
# Swarms CLI Reference
|
||||
|
||||
The Swarms CLI is a comprehensive command-line interface for managing and executing Swarms agents and multi-agent architectures. This reference documents all available commands, arguments, and features.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Installation](#installation)
|
||||
|
||||
- [Basic Usage](#basic-usage)
|
||||
|
||||
- [Commands Reference](#commands-reference)
|
||||
|
||||
- [Global Arguments](#global-arguments)
|
||||
|
||||
- [Command-Specific Arguments](#command-specific-arguments)
|
||||
|
||||
- [Error Handling](#error-handling)
|
||||
|
||||
- [Examples](#examples)
|
||||
|
||||
- [Configuration](#configuration)
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
The CLI is included with the Swarms package installation:
|
||||
|
||||
```bash
|
||||
pip install swarms
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```bash
|
||||
swarms <command> [options]
|
||||
```
|
||||
|
||||
## Commands Reference
|
||||
|
||||
### Core Commands
|
||||
|
||||
| Command | Description | Required Arguments |
|
||||
|---------|-------------|-------------------|
|
||||
| `onboarding` | Start interactive onboarding process | None |
|
||||
| `help` | Display help message | None |
|
||||
| `get-api-key` | Open API key portal in browser | None |
|
||||
| `check-login` | Verify login status and initialize cache | None |
|
||||
| `run-agents` | Execute agents from YAML configuration | `--yaml-file` |
|
||||
| `load-markdown` | Load agents from markdown files | `--markdown-path` |
|
||||
| `agent` | Create and run custom agent | `--name`, `--description`, `--system-prompt`, `--task` |
|
||||
| `auto-upgrade` | Update Swarms to latest version | None |
|
||||
| `book-call` | Schedule strategy session | None |
|
||||
| `autoswarm` | Generate and execute autonomous swarm | `--task`, `--model` |
|
||||
|
||||
## Global Arguments
|
||||
|
||||
All commands support these global options:
|
||||
|
||||
| Argument | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `--verbose` | `bool` | `False` | Enable verbose output |
|
||||
| `--help`, `-h` | `bool` | `False` | Show help message |
|
||||
|
||||
## Command-Specific Arguments
|
||||
|
||||
### `run-agents` Command
|
||||
|
||||
Execute agents from YAML configuration files.
|
||||
|
||||
```bash
|
||||
python -m swarms.cli.main run-agents [options]
|
||||
```
|
||||
|
||||
| Argument | Type | Default | Required | Description |
|
||||
|----------|------|---------|----------|-------------|
|
||||
| `--yaml-file` | `str` | `"agents.yaml"` | No | Path to YAML configuration file |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
swarms run-agents --yaml-file my_agents.yaml
|
||||
```
|
||||
|
||||
### `load-markdown` Command
|
||||
|
||||
Load agents from markdown files with YAML frontmatter.
|
||||
|
||||
```bash
|
||||
python -m swarms.cli.main load-markdown [options]
|
||||
```
|
||||
|
||||
| Argument | Type | Default | Required | Description |
|
||||
|----------|------|---------|----------|-------------|
|
||||
| `--markdown-path` | `str` | `None` | **Yes** | Path to markdown file or directory |
|
||||
| `--concurrent` | `bool` | `True` | No | Enable concurrent processing for multiple files |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
swarms load-markdown --markdown-path ./agents/ --concurrent
|
||||
```
|
||||
|
||||
### `agent` Command
|
||||
|
||||
Create and run a custom agent with specified parameters.
|
||||
|
||||
```bash
|
||||
python -m swarms.cli.main agent [options]
|
||||
```
|
||||
|
||||
#### Required Arguments
|
||||
|
||||
| Argument | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `--name` | `str` | Name of the custom agent |
|
||||
| `--description` | `str` | Description of the custom agent |
|
||||
| `--system-prompt` | `str` | System prompt for the custom agent |
|
||||
| `--task` | `str` | Task for the custom agent to execute |
|
||||
|
||||
#### Optional Arguments
|
||||
|
||||
| Argument | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `--model-name` | `str` | `"gpt-4"` | Model name for the custom agent |
|
||||
| `--temperature` | `float` | `None` | Temperature setting (0.0-2.0) |
|
||||
| `--max-loops` | `int` | `None` | Maximum number of loops for the agent |
|
||||
| `--auto-generate-prompt` | `bool` | `False` | Enable auto-generation of prompts |
|
||||
| `--dynamic-temperature-enabled` | `bool` | `False` | Enable dynamic temperature adjustment |
|
||||
| `--dynamic-context-window` | `bool` | `False` | Enable dynamic context window |
|
||||
| `--output-type` | `str` | `None` | Output type (e.g., 'str', 'json') |
|
||||
| `--verbose` | `bool` | `False` | Enable verbose mode for the agent |
|
||||
| `--streaming-on` | `bool` | `False` | Enable streaming mode for the agent |
|
||||
| `--context-length` | `int` | `None` | Context length for the agent |
|
||||
| `--retry-attempts` | `int` | `None` | Number of retry attempts for the agent |
|
||||
| `--return-step-meta` | `bool` | `False` | Return step metadata from the agent |
|
||||
| `--dashboard` | `bool` | `False` | Enable dashboard for the agent |
|
||||
| `--autosave` | `bool` | `False` | Enable autosave for the agent |
|
||||
| `--saved-state-path` | `str` | `None` | Path for saving agent state |
|
||||
| `--user-name` | `str` | `None` | Username for the agent |
|
||||
| `--mcp-url` | `str` | `None` | MCP URL for the agent |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
swarms agent \
|
||||
--name "Trading Agent" \
|
||||
--description "Advanced trading agent for market analysis" \
|
||||
--system-prompt "You are an expert trader..." \
|
||||
--task "Analyze market trends for AAPL" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.1 \
|
||||
--max-loops 5
|
||||
```
|
||||
|
||||
### `autoswarm` Command
|
||||
|
||||
Generate and execute an autonomous swarm configuration.
|
||||
|
||||
```bash
|
||||
python -m swarms.cli.main autoswarm [options]
|
||||
```
|
||||
|
||||
| Argument | Type | Default | Required | Description |
|
||||
|----------|------|---------|----------|-------------|
|
||||
| `--task` | `str` | `None` | **Yes** | Task description for the swarm |
|
||||
| `--model` | `str` | `None` | **Yes** | Model name to use for the swarm |
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
swarms autoswarm --task "analyze this data" --model "gpt-4"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The CLI provides comprehensive error handling with formatted error messages:
|
||||
|
||||
### Error Types
|
||||
|
||||
| Error Type | Description | Resolution |
|
||||
|------------|-------------|------------|
|
||||
| `FileNotFoundError` | Configuration file not found | Check file path and permissions |
|
||||
| `ValueError` | Invalid configuration format | Verify YAML/markdown syntax |
|
||||
| `SwarmCLIError` | Custom CLI-specific errors | Check command arguments and API keys |
|
||||
| `API Key Error` | Authentication issues | Verify API key configuration |
|
||||
| `Context Length Error` | Model context exceeded | Reduce input size or use larger model |
|
||||
|
||||
### Error Display Format
|
||||
|
||||
Errors are displayed in formatted panels with:
|
||||
|
||||
- **Error Title**: Clear error identification
|
||||
|
||||
- **Error Message**: Detailed error description
|
||||
|
||||
- **Help Text**: Suggested resolution steps
|
||||
|
||||
- **Color Coding**: Red borders for errors, yellow for warnings
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Agent Creation
|
||||
|
||||
```bash
|
||||
# Create a simple agent
|
||||
swarms agent \
|
||||
--name "Code Reviewer" \
|
||||
--description "AI code review assistant" \
|
||||
--system-prompt "You are an expert code reviewer..." \
|
||||
--task "Review this Python code for best practices" \
|
||||
--model-name "gpt-4" \
|
||||
--temperature 0.1
|
||||
```
|
||||
|
||||
### Loading Multiple Agents
|
||||
|
||||
```bash
|
||||
# Load agents from markdown directory
|
||||
swarms load-markdown \
|
||||
--markdown-path ./my_agents/ \
|
||||
--concurrent
|
||||
```
|
||||
|
||||
### Running YAML Configuration
|
||||
|
||||
```bash
|
||||
# Execute agents from YAML file
|
||||
swarms run-agents \
|
||||
--yaml-file production_agents.yaml
|
||||
```
|
||||
|
||||
### Autonomous Swarm Generation
|
||||
|
||||
```bash
|
||||
# Generate swarm for complex task
|
||||
swarms autoswarm \
|
||||
--task "Create a comprehensive market analysis report for tech stocks" \
|
||||
--model "gpt-4"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### YAML Configuration Format
|
||||
|
||||
For `run-agents` command, use this YAML structure:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
- name: "Research Agent"
|
||||
|
||||
description: "Research and analysis specialist"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a research specialist..."
|
||||
temperature: 0.1
|
||||
max_loops: 3
|
||||
|
||||
- name: "Analysis Agent"
|
||||
|
||||
description: "Data analysis expert"
|
||||
model_name: "gpt-4"
|
||||
system_prompt: "You are a data analyst..."
|
||||
temperature: 0.2
|
||||
max_loops: 5
|
||||
```
|
||||
|
||||
### Markdown Configuration Format
|
||||
|
||||
For `load-markdown` command, use YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Research Agent
|
||||
description: AI research specialist
|
||||
model_name: gpt-4
|
||||
temperature: 0.1
|
||||
max_loops: 3
|
||||
---
|
||||
|
||||
You are an expert research agent specializing in...
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Progress Indicators
|
||||
|
||||
The CLI provides rich progress indicators for long-running operations:
|
||||
|
||||
- **Spinner Animations**: Visual feedback during execution
|
||||
|
||||
|
||||
- **Progress Bars**: For operations with known completion states
|
||||
|
||||
- **Status Updates**: Real-time operation status
|
||||
|
||||
|
||||
### Concurrent Processing
|
||||
|
||||
Multiple markdown files can be processed concurrently:
|
||||
|
||||
- **Parallel Execution**: Improves performance for large directories
|
||||
|
||||
- **Resource Management**: Automatic thread management
|
||||
|
||||
- **Error Isolation**: Individual file failures don't affect others
|
||||
|
||||
|
||||
### Auto-upgrade System
|
||||
|
||||
```bash
|
||||
swarms auto-upgrade
|
||||
```
|
||||
|
||||
Automatically updates Swarms to the latest version with:
|
||||
|
||||
- Version checking
|
||||
|
||||
- Dependency resolution
|
||||
|
||||
- Safe update process
|
||||
|
||||
|
||||
### Interactive Onboarding
|
||||
|
||||
```bash
|
||||
swarms onboarding
|
||||
```
|
||||
|
||||
Guided setup process including:
|
||||
|
||||
- API key configuration
|
||||
|
||||
- Environment setup
|
||||
|
||||
- Basic agent creation
|
||||
|
||||
- Usage examples
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **API Key Not Set**
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
2. **File Permissions**
|
||||
```bash
|
||||
chmod 644 agents.yaml
|
||||
```
|
||||
|
||||
3. **Model Not Available**
|
||||
- Verify model name spelling
|
||||
|
||||
- Check API key permissions
|
||||
|
||||
- Ensure sufficient quota
|
||||
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose output for debugging:
|
||||
|
||||
```bash
|
||||
swarms <command> --verbose
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
The CLI can be integrated into CI/CD pipelines:
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Run Swarms Agents
|
||||
|
||||
run: |
|
||||
swarms run-agents --yaml-file ci_agents.yaml
|
||||
```
|
||||
|
||||
### Scripting
|
||||
|
||||
Use in shell scripts:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Run multiple agent configurations
|
||||
swarms run-agents --yaml-file agents1.yaml
|
||||
swarms run-agents --yaml-file agents2.yaml
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
| Consideration | Recommendation |
|
||||
|------------------------|-----------------------------------------------------|
|
||||
| Concurrent Processing | Use `--concurrent` for multiple files |
|
||||
| Model Selection | Choose appropriate models for task complexity |
|
||||
| Context Length | Monitor and optimize input sizes |
|
||||
| Rate Limiting | Respect API provider limits |
|
||||
|
||||
## Security
|
||||
|
||||
| Security Aspect | Recommendation |
|
||||
|------------------------|--------------------------------------------------------|
|
||||
| API Key Management | Store keys in environment variables |
|
||||
| File Permissions | Restrict access to configuration files |
|
||||
| Input Validation | CLI validates all inputs before execution |
|
||||
| Error Sanitization | Sensitive information is not exposed in errors |
|
||||
|
||||
## Support
|
||||
|
||||
For additional support:
|
||||
|
||||
| Support Option | Link |
|
||||
|----------------------|---------------------------------------------------------------------------------------|
|
||||
| **Community** | [Discord](https://discord.gg/EamjgSaEQf) |
|
||||
| **Issues** | [GitHub Issues](https://github.com/kyegomez/swarms/issues) |
|
||||
| **Strategy Sessions**| [Book a Call](https://cal.com/swarms/swarms-strategy-session) |
|
||||
@ -1,5 +0,0 @@
|
||||
from swarms.utils import load_agent_from_markdown
|
||||
|
||||
agent = load_agent_from_markdown("finance_advisor.md")
|
||||
|
||||
agent.run(task="Analyze the financial market trends for 2023.")
|
||||
@ -0,0 +1,35 @@
|
||||
from swarms.utils import load_agent_from_markdown
|
||||
|
||||
agent = load_agent_from_markdown("finance_advisor.md")
|
||||
|
||||
agent.run(task="What were the best performing etfs in 2023")
|
||||
|
||||
|
||||
# ---
|
||||
# name: FinanceAdvisor
|
||||
# description: Expert financial advisor for investment and budgeting guidance
|
||||
# model_name: gpt-4o
|
||||
# temperature: 0.7
|
||||
# max_loops: 1
|
||||
# ---
|
||||
|
||||
# You are an expert financial advisor with deep knowledge in:
|
||||
# - Investment strategies and portfolio management
|
||||
# - Personal budgeting and financial planning
|
||||
# - Risk assessment and diversification
|
||||
# - Tax optimization strategies
|
||||
# - Retirement planning
|
||||
|
||||
# Your approach:
|
||||
# - Provide clear, actionable financial advice
|
||||
# - Consider individual risk tolerance and goals
|
||||
# - Explain complex concepts in simple terms
|
||||
# - Always emphasize the importance of diversification
|
||||
# - Include relevant disclaimers about financial advice
|
||||
|
||||
# When analyzing financial situations:
|
||||
# 1. Assess current financial position
|
||||
# 2. Identify short-term and long-term goals
|
||||
# 3. Evaluate risk tolerance
|
||||
# 4. Recommend appropriate strategies
|
||||
# 5. Suggest specific action steps
|
||||
Loading…
Reference in new issue