diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 35f9d149..86fd21bf 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -318,6 +318,7 @@ nav: - Communication Structure: "swarms/structs/conversation.md" - Utilities: + - CLI Reference: "swarms/cli/cli_reference.md" - Agent Loader: "swarms/utils/agent_loader.md" - AgentRegistry: "swarms/structs/agent_registry.md" @@ -354,6 +355,8 @@ nav: - Paper Implementations: "examples/paper_implementations.md" - Templates & Applications: "examples/templates.md" - Community Resources: "examples/community_resources.md" + - CLI Examples: "swarms/cli/cli_examples.md" + - Basic Examples: - Individual Agents: - Basic Agent: "swarms/examples/basic_agent.md" diff --git a/docs/swarms/cli/cli_examples.md b/docs/swarms/cli/cli_examples.md new file mode 100644 index 00000000..c3ec9997 --- /dev/null +++ b/docs/swarms/cli/cli_examples.md @@ -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. diff --git a/docs/swarms/cli/cli_reference.md b/docs/swarms/cli/cli_reference.md new file mode 100644 index 00000000..750eb76d --- /dev/null +++ b/docs/swarms/cli/cli_reference.md @@ -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 [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 --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) | diff --git a/examples/agent_loader/agent_loader_demo.py b/examples/agent_loader/agent_loader_demo.py deleted file mode 100644 index be0d9306..00000000 --- a/examples/agent_loader/agent_loader_demo.py +++ /dev/null @@ -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.") diff --git a/examples/paper_implementations/long_agent.py b/examples/multi_agent/paper_implementations/long_agent.py similarity index 100% rename from examples/paper_implementations/long_agent.py rename to examples/multi_agent/paper_implementations/long_agent.py diff --git a/examples/utils/agent_loader/agent_loader_demo.py b/examples/utils/agent_loader/agent_loader_demo.py new file mode 100644 index 00000000..13accc4c --- /dev/null +++ b/examples/utils/agent_loader/agent_loader_demo.py @@ -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 diff --git a/examples/agent_loader/finance_advisor.md b/examples/utils/agent_loader/finance_advisor.md similarity index 100% rename from examples/agent_loader/finance_advisor.md rename to examples/utils/agent_loader/finance_advisor.md diff --git a/examples/agent_loader/multi_agents_loader_demo.py b/examples/utils/agent_loader/multi_agents_loader_demo.py similarity index 100% rename from examples/agent_loader/multi_agents_loader_demo.py rename to examples/utils/agent_loader/multi_agents_loader_demo.py diff --git a/examples/communication_examples/duckdb_agent.py b/examples/utils/communication_examples/duckdb_agent.py similarity index 100% rename from examples/communication_examples/duckdb_agent.py rename to examples/utils/communication_examples/duckdb_agent.py diff --git a/examples/communication_examples/pulsar_conversation.py b/examples/utils/communication_examples/pulsar_conversation.py similarity index 100% rename from examples/communication_examples/pulsar_conversation.py rename to examples/utils/communication_examples/pulsar_conversation.py diff --git a/examples/communication_examples/redis_conversation.py b/examples/utils/communication_examples/redis_conversation.py similarity index 100% rename from examples/communication_examples/redis_conversation.py rename to examples/utils/communication_examples/redis_conversation.py diff --git a/examples/communication_examples/sqlite_conversation.py b/examples/utils/communication_examples/sqlite_conversation.py similarity index 100% rename from examples/communication_examples/sqlite_conversation.py rename to examples/utils/communication_examples/sqlite_conversation.py diff --git a/swarms/__init__.py b/swarms/__init__.py index 10188655..6539e20a 100644 --- a/swarms/__init__.py +++ b/swarms/__init__.py @@ -7,7 +7,6 @@ from swarms.telemetry.bootup import bootup # noqa: E402, F403 bootup() from swarms.agents import * # noqa: E402, F403 - from swarms.artifacts import * # noqa: E402, F403 from swarms.prompts import * # noqa: E402, F403 from swarms.schemas import * # noqa: E402, F403 diff --git a/swarms/cli/main.py b/swarms/cli/main.py index 48feec94..5dadbfde 100644 --- a/swarms/cli/main.py +++ b/swarms/cli/main.py @@ -16,6 +16,8 @@ from swarms.agents.create_agents_from_yaml import ( create_agents_from_yaml, ) from swarms.cli.onboarding_process import OnboardingProcess +from swarms.structs.agent import Agent +from swarms.utils.agent_loader import AgentLoader from swarms.utils.formatter import formatter # Initialize console with custom styling @@ -39,16 +41,13 @@ COLORS = { "text": "#FFFFFF", } -ASCII_ART = """ - ▄████████ ▄█ █▄ ▄████████ ▄████████ ▄▄▄▄███▄▄▄▄ ▄████████ - ███ ███ ███ ███ ███ ███ ███ ███ ▄██▀▀▀███▀▀▀██▄ ███ ███ - ███ █▀ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ █▀ - ███ ███ ███ ███ ███ ▄███▄▄▄▄██▀ ███ ███ ███ ███ -▀███████████ ███ ███ ▀███████████ ▀▀███▀▀▀▀▀ ███ ███ ███ ▀███████████ - ███ ███ ███ ███ ███ ▀███████████ ███ ███ ███ ███ - ▄█ ███ ███ ▄█▄ ███ ███ ███ ███ ███ ███ ███ ███ ▄█ ███ - ▄████████▀ ▀███▀███▀ ███ █▀ ███ ███ ▀█ ███ █▀ ▄████████▀ - ███ ███ +ASCII_ART = r""" + _________ + / _____/_ _ _______ _______ _____ ______ + \_____ \\ \/ \/ /\__ \\_ __ \/ \ / ___/ + / \\ / / __ \| | \/ Y Y \\___ \ +/_______ / \/\_/ (____ /__| |__|_| /____ > + \/ \/ \/ \/ """ @@ -91,6 +90,11 @@ def create_command_table() -> Table: ("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"), @@ -180,11 +184,6 @@ def run_autoswarm(task: str, model: str): "[yellow]Initializing autoswarm configuration...[/yellow]" ) - # Set LiteLLM verbose mode for debugging - import litellm - - litellm.set_verbose = True - # Validate inputs if not task or task.strip() == "": raise SwarmCLIError("Task cannot be empty") @@ -226,6 +225,234 @@ def run_autoswarm(task: str, model: str): ) +def load_markdown_agents( + file_path: str, concurrent: bool = True, **kwargs +): + """Load agents from markdown files with enhanced visual feedback.""" + try: + console.print( + f"[yellow]Loading agents from markdown: {file_path}[/yellow]" + ) + + # Create progress display + progress = Progress( + SpinnerColumn(), + TextColumn("[progress.description]{task.description}"), + console=console, + ) + + with progress: + # Add initial task + init_task = progress.add_task( + "Initializing markdown loader...", total=None + ) + + # Initialize agent loader + progress.update( + init_task, + description="Initializing agent loader...", + ) + loader = AgentLoader() + + # Load agents + progress.update( + init_task, + description="Loading agents from markdown...", + ) + + if os.path.isdir(file_path): + agents = loader.load_multiple_agents( + file_path, concurrent=concurrent, **kwargs + ) + else: + agents = [ + loader.load_single_agent(file_path, **kwargs) + ] + + # Update progress on completion + progress.update( + init_task, + description="Processing complete!", + completed=True, + ) + + # Display results + if agents: + console.print( + f"\n[bold green]✓ Successfully loaded {len(agents)} agents![/bold green]" + ) + + # Create a table to display loaded agents + agent_table = Table( + show_header=True, + header_style=f"bold {COLORS['primary']}", + border_style=COLORS["secondary"], + title="Loaded Agents", + padding=(0, 2), + ) + + agent_table.add_column("Name", style="bold white") + agent_table.add_column("Model", style="dim white") + agent_table.add_column("Description", style="dim white") + + for agent in agents: + name = getattr(agent, "agent_name", "Unknown") + model = getattr(agent, "model_name", "Unknown") + description = getattr( + agent, "agent_description", "No description" + ) + + agent_table.add_row(name, model, description) + + console.print(agent_table) + + return agents + else: + console.print( + "[yellow]⚠ No agents were loaded from the markdown files.[/yellow]" + ) + return [] + + except FileNotFoundError: + show_error( + "File Error", + f"Markdown file/directory not found: {file_path}\n" + "Please make sure the path exists and you're in the correct directory.", + ) + return [] + except ValueError as e: + show_error( + "Configuration Error", + f"Error parsing markdown: {str(e)}\n\n" + "Please check that your markdown files use the correct YAML frontmatter format:\n" + "---\n" + "name: Agent Name\n" + "description: Agent Description\n" + "model_name: gpt-4\n" + "temperature: 0.1\n" + "---\n" + "System prompt content here...", + ) + return [] + except Exception as e: + show_error( + "Execution Error", + f"An unexpected error occurred: {str(e)}\n" + "1. Check your markdown file format\n" + "2. Verify your API keys are set\n" + "3. Check network connectivity", + ) + return [] + + +def create_swarm_agent( + name: str, + description: str, + system_prompt: str, + model_name: str, + task: str, + **kwargs +): + """Create and run a custom agent with the specified parameters.""" + try: + console.print( + f"[yellow]Creating custom agent: {name}[/yellow]" + ) + + # Create progress display + progress = Progress( + SpinnerColumn(), + TextColumn( + "[progress.description]{task.description}" + ), + console=console, + ) + + with progress: + # Add initial task + init_task = progress.add_task( + "Initializing agent...", total=None + ) + + # Create agent + progress.update( + init_task, + description="Creating agent with specified parameters...", + ) + + # Build agent configuration + agent_config = { + "agent_name": name, + "agent_description": description, + "system_prompt": system_prompt, + "model_name": model_name, + **kwargs + } + + # Remove None values to use defaults + agent_config = {k: v for k, v in agent_config.items() if v is not None} + + agent = Agent(**agent_config) + + # Update progress + progress.update( + init_task, + description="Agent created successfully! Running task...", + ) + + # Run the agent with the specified task + progress.update( + init_task, + description=f"Executing task: {task[:50]}...", + ) + + result = agent.run(task) + + # Update progress on completion + progress.update( + init_task, + description="Task completed!", + completed=True, + ) + + # Display results + if result: + console.print( + f"\n[bold green]✓ Agent '{name}' completed the task successfully![/bold green]" + ) + + # Display agent info + agent_info = Panel( + f"[bold]Agent Name:[/bold] {name}\n" + f"[bold]Model:[/bold] {model_name}\n" + f"[bold]Task:[/bold] {task}\n" + f"[bold]Result:[/bold]\n{result}", + title="Agent Execution Results", + border_style="green", + padding=(1, 2) + ) + console.print(agent_info) + + return result + else: + console.print( + f"[yellow]⚠ Agent '{name}' completed but returned no results.[/yellow]" + ) + return None + + except Exception as e: + show_error( + "Agent Creation Error", + f"Failed to create or run agent: {str(e)}\n\n" + "Please check:\n" + "1. Your API keys are set correctly\n" + "2. The model name is valid\n" + "3. All required parameters are provided\n" + "4. Your system prompt is properly formatted" + ) + return None + + def main(): try: @@ -242,6 +469,8 @@ def main(): "get-api-key", "check-login", "run-agents", + "load-markdown", + "agent", "auto-upgrade", "book-call", "autoswarm", @@ -255,13 +484,122 @@ def main(): help="YAML configuration file path", ) parser.add_argument( - "--task", type=str, help="Task for autoswarm" + "--markdown-path", + type=str, + help="Path to markdown file or directory containing markdown files", + ) + parser.add_argument( + "--concurrent", + action="store_true", + default=True, + help="Enable concurrent processing for multiple markdown files (default: True)", + ) + # Swarm agent specific arguments + parser.add_argument( + "--name", + type=str, + help="Name of the custom agent", + ) + parser.add_argument( + "--description", + type=str, + help="Description of the custom agent", + ) + parser.add_argument( + "--system-prompt", + type=str, + help="System prompt for the custom agent", ) parser.add_argument( - "--model", + "--model-name", type=str, default="gpt-4", - help="Model for autoswarm", + help="Model name for the custom agent (default: gpt-4)", + ) + parser.add_argument( + "--task", + type=str, + help="Task for the custom agent to execute", + ) + parser.add_argument( + "--temperature", + type=float, + help="Temperature setting for the agent (0.0-2.0)", + ) + parser.add_argument( + "--max-loops", + type=int, + help="Maximum number of loops for the agent", + ) + parser.add_argument( + "--auto-generate-prompt", + action="store_true", + help="Enable auto-generation of prompts", + ) + parser.add_argument( + "--dynamic-temperature-enabled", + action="store_true", + help="Enable dynamic temperature adjustment", + ) + parser.add_argument( + "--dynamic-context-window", + action="store_true", + help="Enable dynamic context window", + ) + parser.add_argument( + "--output-type", + type=str, + help="Output type for the agent (e.g., 'str', 'json')", + ) + parser.add_argument( + "--verbose", + action="store_true", + help="Enable verbose mode for the agent", + ) + parser.add_argument( + "--streaming-on", + action="store_true", + help="Enable streaming mode for the agent", + ) + parser.add_argument( + "--context-length", + type=int, + help="Context length for the agent", + ) + parser.add_argument( + "--retry-attempts", + type=int, + help="Number of retry attempts for the agent", + ) + parser.add_argument( + "--return-step-meta", + action="store_true", + help="Return step metadata from the agent", + ) + parser.add_argument( + "--dashboard", + action="store_true", + help="Enable dashboard for the agent", + ) + parser.add_argument( + "--autosave", + action="store_true", + help="Enable autosave for the agent", + ) + parser.add_argument( + "--saved-state-path", + type=str, + help="Path for saving agent state", + ) + parser.add_argument( + "--user-name", + type=str, + help="Username for the agent", + ) + parser.add_argument( + "--mcp-url", + type=str, + help="MCP URL for the agent", ) args = parser.parse_args() @@ -390,6 +728,85 @@ def main(): "2. Verify your API keys are set\n" "3. Check network connectivity", ) + elif args.command == "load-markdown": + if not args.markdown_path: + show_error( + "Missing required argument: --markdown-path", + "Example usage: python cli.py load-markdown --markdown-path ./agents/", + ) + exit(1) + + # Load agents from markdown + agents = load_markdown_agents( + args.markdown_path, + concurrent=args.concurrent + ) + + if agents: + console.print( + f"\n[bold green]Ready to use {len(agents)} agents![/bold green]\n" + "[dim]You can now use these agents in your code or run them interactively.[/dim]" + ) + elif args.command == "agent": + # Validate required arguments + required_args = ["name", "description", "system_prompt", "task"] + missing_args = [arg for arg in required_args if not getattr(args, arg)] + + if missing_args: + show_error( + "Missing required arguments", + f"Required arguments: {', '.join(missing_args)}\n\n" + "Example usage:\n" + "python cli.py agent \\\n" + " --name 'Trading Agent' \\\n" + " --description 'Advanced trading agent' \\\n" + " --system-prompt 'You are an expert trader...' \\\n" + " --task 'Analyze market trends' \\\n" + " --model-name 'gpt-4' \\\n" + " --temperature 0.1" + ) + exit(1) + + # Build kwargs for additional parameters + additional_params = {} + param_mapping = { + 'temperature': 'temperature', + 'max_loops': 'max_loops', + 'auto_generate_prompt': 'auto_generate_prompt', + 'dynamic_temperature_enabled': 'dynamic_temperature_enabled', + 'dynamic_context_window': 'dynamic_context_window', + 'output_type': 'output_type', + 'verbose': 'verbose', + 'streaming_on': 'streaming_on', + 'context_length': 'context_length', + 'retry_attempts': 'retry_attempts', + 'return_step_meta': 'return_step_meta', + 'dashboard': 'dashboard', + 'autosave': 'autosave', + 'saved_state_path': 'saved_state_path', + 'user_name': 'user_name', + 'mcp_url': 'mcp_url' + } + + for cli_arg, agent_param in param_mapping.items(): + value = getattr(args, cli_arg) + if value is not None: + additional_params[agent_param] = value + + # Create and run the custom agent + result = create_swarm_agent( + name=args.name, + description=args.description, + system_prompt=args.system_prompt, + model_name=args.model_name, + task=args.task, + **additional_params + ) + + if result: + console.print( + f"\n[bold green]Agent '{args.name}' executed successfully![/bold green]" + ) elif args.command == "book-call": webbrowser.open( "https://cal.com/swarms/swarms-strategy-session" diff --git a/swarms/utils/agent_loader.py b/swarms/utils/agent_loader.py index fbc0d5d5..415daac0 100644 --- a/swarms/utils/agent_loader.py +++ b/swarms/utils/agent_loader.py @@ -1,7 +1,7 @@ import os import yaml from pathlib import Path -from typing import Any, Dict, List, Optional, Union +from typing import Any, Dict, List, Optional, Union, TYPE_CHECKING from concurrent.futures import ( ThreadPoolExecutor, as_completed, @@ -10,37 +10,38 @@ from concurrent.futures import ( from pydantic import BaseModel, Field, field_validator from loguru import logger +# Type checking imports to avoid circular dependency +if TYPE_CHECKING: + from swarms.structs.agent import Agent + # Lazy import to avoid circular dependency # Default model configuration -DEFAULT_MODEL = "gpt-4o" +DEFAULT_MODEL = "gpt-4.1" class MarkdownAgentConfig(BaseModel): """Configuration model for agents loaded from Claude Code markdown files.""" - name: str - description: str - model_name: Optional[str] = "gpt-4o" + name: Optional[str] = None + description: Optional[str] = None + model_name: Optional[str] = DEFAULT_MODEL temperature: Optional[float] = Field(default=0.1, ge=0.0, le=2.0) mcp_url: Optional[int] = None - system_prompt: str - max_loops: int = Field(default=1, ge=1) - autosave: bool = False - dashboard: bool = False - verbose: bool = False - dynamic_temperature_enabled: bool = False + system_prompt: Optional[str] = None + max_loops: Optional[int] = Field(default=1, ge=1) + autosave: Optional[bool] = False + dashboard: Optional[bool] = False + verbose: Optional[bool] = False + dynamic_temperature_enabled: Optional[bool] = False saved_state_path: Optional[str] = None - user_name: str = "default_user" - retry_attempts: int = Field(default=3, ge=1) - context_length: int = Field(default=100000, ge=1000) - return_step_meta: bool = False - output_type: str = "str" - auto_generate_prompt: bool = False - artifacts_on: bool = False - artifacts_file_extension: str = ".md" - artifacts_output_path: str = "" - streaming_on: bool = False + user_name: Optional[str] = "default_user" + retry_attempts: Optional[int] = Field(default=3, ge=1) + context_length: Optional[int] = Field(default=100000, ge=1000) + return_step_meta: Optional[bool] = False + output_type: Optional[str] = "str" + auto_generate_prompt: Optional[bool] = False + streaming_on: Optional[bool] = False @field_validator("system_prompt") @classmethod @@ -67,11 +68,12 @@ class AgentLoader: - Error handling and validation """ - def __init__(self): + def __init__(self, max_workers: Optional[int] = None): """ Initialize the AgentLoader. """ - pass + self.max_workers = max_workers + self.max_workers = os.cpu_count() * 2 def parse_yaml_frontmatter(self, content: str) -> Dict[str, Any]: """ @@ -197,6 +199,9 @@ class AgentLoader: Returns: Configured Agent instance """ + # Lazy import to avoid circular dependency + from swarms.structs.agent import Agent + config = self.parse_markdown_file(file_path) # Override with any provided kwargs @@ -206,8 +211,8 @@ class AgentLoader: # Map config fields to Agent parameters, handling special cases field_mapping = { "name": "agent_name", # name -> agent_name - "description": None, # not used by Agent - "mcp_url": None, # not used by Agent + "description": "agent_description", # not used by Agent + "mcp_url": "mcp_url", # not used by Agent } agent_fields = {} @@ -222,8 +227,6 @@ class AgentLoader: agent_fields[config_key] = config_value try: - # Lazy import to avoid circular dependency - from swarms.structs.agent import Agent logger.info( f"Creating agent '{config.name}' from {file_path}" @@ -248,7 +251,6 @@ class AgentLoader: self, file_paths: Union[str, List[str]], concurrent: bool = True, - max_workers: Optional[int] = None, max_file_size_mb: float = 10.0, **kwargs, ) -> List["Agent"]: @@ -258,13 +260,14 @@ class AgentLoader: Args: file_paths: Single file path, directory path, or list of file paths concurrent: Whether to use concurrent processing for multiple files - max_workers: Maximum number of worker threads (defaults to CPU count) max_file_size_mb: Maximum file size in MB to prevent memory issues **kwargs: Additional arguments to override default configuration Returns: List of configured Agent instances """ + # Lazy import to avoid circular dependency + agents = [] paths_to_process = [] @@ -304,21 +307,14 @@ class AgentLoader: f"Could not check size of {file_path}, skipping validation" ) - # Adjust max_workers for I/O-bound operations - if max_workers is None and concurrent: - # For I/O-bound: use more threads than CPU count, but cap it - max_workers = min( - 20, len(paths_to_process), os.cpu_count() * 2 - ) - # Use concurrent processing for multiple files if enabled if concurrent and len(paths_to_process) > 1: logger.info( - f"Loading {len(paths_to_process)} agents concurrently with {max_workers} workers..." + f"Loading {len(paths_to_process)} agents concurrently with {self.max_workers} workers..." ) with ThreadPoolExecutor( - max_workers=max_workers + max_workers=self.max_workers ) as executor: # Submit all tasks future_to_path = { @@ -385,6 +381,8 @@ class AgentLoader: Returns: Configured Agent instance """ + # Lazy import to avoid circular dependency + return self.load_agent_from_markdown(file_path, **kwargs) def load_multiple_agents( @@ -401,6 +399,8 @@ class AgentLoader: Returns: List of configured Agent instances """ + # Lazy import to avoid circular dependency + return self.load_agents_from_markdown(file_paths, **kwargs) @@ -416,6 +416,8 @@ def load_agent_from_markdown(file_path: str, **kwargs) -> "Agent": Returns: Configured Agent instance """ + # Lazy import to avoid circular dependency + loader = AgentLoader() return loader.load_single_agent(file_path, **kwargs) @@ -438,6 +440,8 @@ def load_agents_from_markdown( Returns: List of configured Agent instances """ + # Lazy import to avoid circular dependency + loader = AgentLoader() return loader.load_agents_from_markdown( file_paths, diff --git a/tests/agents/test_agent_logging.py b/tests/agent/agents/test_agent_logging.py similarity index 100% rename from tests/agents/test_agent_logging.py rename to tests/agent/agents/test_agent_logging.py diff --git a/tests/agents/test_create_agents_from_yaml.py b/tests/agent/agents/test_create_agents_from_yaml.py similarity index 100% rename from tests/agents/test_create_agents_from_yaml.py rename to tests/agent/agents/test_create_agents_from_yaml.py diff --git a/tests/agents/test_litellm_args_kwargs.py b/tests/agent/agents/test_litellm_args_kwargs.py similarity index 100% rename from tests/agents/test_litellm_args_kwargs.py rename to tests/agent/agents/test_litellm_args_kwargs.py diff --git a/tests/agents/test_llm_args.py b/tests/agent/agents/test_llm_args.py similarity index 100% rename from tests/agents/test_llm_args.py rename to tests/agent/agents/test_llm_args.py diff --git a/tests/agents/test_llm_handling_args.py b/tests/agent/agents/test_llm_handling_args.py similarity index 100% rename from tests/agents/test_llm_handling_args.py rename to tests/agent/agents/test_llm_handling_args.py diff --git a/tests/agents/test_tool_agent.py b/tests/agent/agents/test_tool_agent.py similarity index 100% rename from tests/agents/test_tool_agent.py rename to tests/agent/agents/test_tool_agent.py diff --git a/tests/benchmark_agent/test_agent_exec_benchmark.py b/tests/agent/benchmark_agent/test_agent_exec_benchmark.py similarity index 100% rename from tests/benchmark_agent/test_agent_exec_benchmark.py rename to tests/agent/benchmark_agent/test_agent_exec_benchmark.py diff --git a/tests/benchmark_agent/test_auto_test_eval.py b/tests/agent/benchmark_agent/test_auto_test_eval.py similarity index 100% rename from tests/benchmark_agent/test_auto_test_eval.py rename to tests/agent/benchmark_agent/test_auto_test_eval.py diff --git a/tests/benchmark_agent/test_benchmark_init.py b/tests/agent/benchmark_agent/test_benchmark_init.py similarity index 100% rename from tests/benchmark_agent/test_benchmark_init.py rename to tests/agent/benchmark_agent/test_benchmark_init.py diff --git a/tests/benchmark_agent/test_github_summarizer_agent.py b/tests/agent/benchmark_agent/test_github_summarizer_agent.py similarity index 100% rename from tests/benchmark_agent/test_github_summarizer_agent.py rename to tests/agent/benchmark_agent/test_github_summarizer_agent.py diff --git a/tests/benchmark_agent/test_profiling_agent.py b/tests/agent/benchmark_agent/test_profiling_agent.py similarity index 100% rename from tests/benchmark_agent/test_profiling_agent.py rename to tests/agent/benchmark_agent/test_profiling_agent.py diff --git a/tests/test_graph_workflow_comprehensive.py b/tests/structs/test_graph_workflow_comprehensive.py similarity index 100% rename from tests/test_graph_workflow_comprehensive.py rename to tests/structs/test_graph_workflow_comprehensive.py diff --git a/tests/test_conversation.py b/tests/utils/test_conversation.py similarity index 100% rename from tests/test_conversation.py rename to tests/utils/test_conversation.py