diff --git a/.env.example b/.env.example index b8ccaf86..a7bd6b36 100644 --- a/.env.example +++ b/.env.example @@ -16,6 +16,8 @@ GEMINI_API_KEY="" ## Hugging Face HUGGINGFACE_TOKEN="" +GROQ_API_KEY="" + ## Perplexity AI PPLX_API_KEY="" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ec3b0b1e..b6c7f57b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -140,6 +140,14 @@ markdown_extensions: nav: - Home: + - Overview: "quickstart.md" + - Installation: "swarms/install/install.md" + - Environment Configuration: "swarms/install/env.md" + - Agents: "swarms/agents/index.md" + - Multi-Agent Architectures: "swarms/structs/index.md" + # - Learn More: "swarms/learn_more/index.md" + + - Guides: - Overview: "index.md" - Onboarding: - Installation: "swarms/install/install.md" @@ -147,7 +155,6 @@ nav: - Quickstart: "swarms/install/quickstart.md" - Feature Set: "swarms/features.md" - Agents: - # - Overview: "swarms/structs/index.md" - Overview: "swarms/agents/index.md" - Concepts: # - Managing Prompts in Production: "swarms/prompts/main.md" @@ -260,7 +267,6 @@ nav: - Examples: - Overview: "examples/index.md" - CookBook Index: "examples/cookbook_index.md" - # - PreBuilt Templates: "examples/templates_index.md" - Basic Examples: - Individual Agents: - Basic Agent: "swarms/examples/basic_agent.md" @@ -319,11 +325,6 @@ nav: - Swarms of Browser Agents: "swarms/examples/swarms_of_browser_agents.md" - ConcurrentWorkflow with VLLM Agents: "swarms/examples/vllm.md" - - - Swarms API Examples: - - Medical Swarm: "swarms/examples/swarms_api_medical.md" - - Finance Swarm: "swarms/examples/swarms_api_finance.md" - # - ML Model Code Generation Swarm: "swarms/examples/swarms_api_ml_model.md" # - Swarm Models: # - Overview: "swarms/models/index.md" @@ -346,25 +347,29 @@ nav: # - GPT4VisionAPI: "swarms/models/gpt4v.md" - Swarms Cloud API: - Overview: "swarms_cloud/swarms_api.md" - - Swarms API as MCP: "swarms_cloud/mcp.md" - - Swarms API Tools: "swarms_cloud/swarms_api_tools.md" - - Individual Agent Completions: "swarms_cloud/agent_api.md" + - Quickstart: "swarms_cloud/quickstart.md" + - MCP Server: "swarms_cloud/mcp.md" + - Rate Limits: "swarms_cloud/rate_limits.md" + - Best Practices: "swarms_cloud/best_practices.md" + + - Capabilities: + - Agents: + - Individual Agent Completions: "swarms_cloud/agent_api.md" + - Tools: "swarms_cloud/swarms_api_tools.md" + - Multi-Agent: + - Multi Agent Architectures Available: "swarms_cloud/swarm_types.md" + - Examples: + - Medical Swarm: "swarms/examples/swarms_api_medical.md" + - Finance Swarm: "swarms/examples/swarms_api_finance.md" - Clients: - - Swarms API Python Client: "swarms_cloud/python_client.md" - - Swarms API Rust Client: "swarms_cloud/rust_client.md" + - Python Client: "swarms_cloud/python_client.md" + - Rust Client: "swarms_cloud/rust_client.md" - Pricing: - - Swarms API Pricing: "swarms_cloud/api_pricing.md" - - Swarms API Pricing in Chinese: "swarms_cloud/chinese_api_pricing.md" - - Swarms Cloud Subscription Tiers: "swarms_cloud/subscription_tiers.md" - - - Swarm Ecosystem APIs: - - MCS API: "swarms_cloud/mcs_api.md" - # - CreateNow API: "swarms_cloud/create_api.md" - - Guides: - - Swarms API Best Practices: "swarms_cloud/best_practices.md" - - Multi Agent Architectures Available: "swarms_cloud/swarm_types.md" + - Pricing: "swarms_cloud/api_pricing.md" + - Pricing in Chinese: "swarms_cloud/chinese_api_pricing.md" + - Subscription Tiers: "swarms_cloud/subscription_tiers.md" - Swarms Marketplace: - Overview: "swarms_platform/index.md" diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..0ab70ba7 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,387 @@ + +# Welcome to Swarms Docs Home + +[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/jM3Z6M9uMq) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp) + +## What is Swarms? + +**Swarms** is the **first and most reliable multi-agent production-grade framework** designed to orchestrate intelligent AI agents at scale. Built for enterprise applications, Swarms enables you to create sophisticated multi-agent systems that can handle complex tasks through collaboration, parallel processing, and intelligent task distribution. + +### Key Capabilities + +- **🏢 Production-Ready**: Enterprise-grade infrastructure with high reliability, comprehensive logging, and robust error handling +- **🤖 Multi-Agent Orchestration**: Support for hierarchical swarms, parallel processing, sequential workflows, and dynamic agent rearrangement +- **🔄 Flexible Integration**: Multi-model support, custom agent creation, extensive tool library, and multiple memory systems +- **📈 Scalable Architecture**: Concurrent processing, resource management, load balancing, and horizontal scaling capabilities +- **🛠️ Developer-Friendly**: Simple API, extensive documentation, active community, and CLI tools for rapid development +- **🔐 Enterprise Security**: Built-in error handling, rate limiting, monitoring integration, and audit logging + +### Why Choose Swarms? + +Swarms stands out as the **most reliable multi-agent framework** because it was built from the ground up for production environments. Unlike other frameworks that focus on research or simple demos, Swarms provides the infrastructure, tooling, and best practices needed to deploy multi-agent systems in real-world applications. + +Whether you're building financial analysis systems, healthcare diagnostics, manufacturing optimization, or any other complex multi-agent application, Swarms provides the foundation you need to succeed. + +Get started learning swarms with the following examples and more. + +## Install 💻 + +```bash +$ pip3 install -U swarms +``` + +### Using uv (Recommended) +[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust. + +```bash +# Install uv +$ curl -LsSf https://astral.sh/uv/install.sh | sh + +# Install swarms using uv +$ uv pip install swarms +``` + +### Using poetry +```bash +# Install poetry if you haven't already +$ curl -sSL https://install.python-poetry.org | python3 - + +# Add swarms to your project +$ poetry add swarms +``` + +### From source +```bash +# Clone the repository +$ git clone https://github.com/kyegomez/swarms.git +$ cd swarms + +# Install with pip +$ pip install -e . +``` + +--- + +## Environment Configuration + +[Learn more about the environment configuration here](https://docs.swarms.world/en/latest/swarms/install/env/) + +``` +OPENAI_API_KEY="" +WORKSPACE_DIR="agent_workspace" +ANTHROPIC_API_KEY="" +GROQ_API_KEY="" +``` + + + +### 🤖 Your First Agent + +An **Agent** is the fundamental building block of a swarm—an autonomous entity powered by an LLM + Tools + Memory. [Learn more Here](https://docs.swarms.world/en/latest/swarms/structs/agent/) + +```python +from swarms import Agent + +# Initialize a new agent +agent = Agent( + model_name="gpt-4o-mini", # Specify the LLM + max_loops=1, # Set the number of interactions + interactive=True, # Enable interactive mode for real-time feedback +) + +# Run the agent with a task +agent.run("What are the key benefits of using a multi-agent system?") +``` + +### 🤝 Your First Swarm: Multi-Agent Collaboration + +A **Swarm** consists of multiple agents working together. This simple example creates a two-agent workflow for researching and writing a blog post. [Learn More About SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/) + +```python +from swarms import Agent, SequentialWorkflow + +# Agent 1: The Researcher +researcher = Agent( + agent_name="Researcher", + system_prompt="Your job is to research the provided topic and provide a detailed summary.", + model_name="gpt-4o-mini", +) + +# Agent 2: The Writer +writer = Agent( + agent_name="Writer", + system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.", + model_name="gpt-4o-mini", +) + +# Create a sequential workflow where the researcher's output feeds into the writer's input +workflow = SequentialWorkflow(agents=[researcher, writer]) + +# Run the workflow on a task +final_post = workflow.run("The history and future of artificial intelligence") +print(final_post) + +``` + +----- + +## 🏗️ Multi-Agent Architectures For Production Deployments + +`swarms` provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems. + +| **Architecture** | **Description** | **Best For** | +|---|---|---| +| **[SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** | Agents execute tasks in a linear chain; one agent's output is the next one's input. | Step-by-step processes like data transformation pipelines, report generation. | +| **[ConcurrentWorkflow](https://docs.swarms.world/en/latest/swarms/structs/concurrent_workflow/)** | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks like batch processing, parallel data analysis. | +| **[AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** | Dynamically maps complex relationships (e.g., `a -> b, c`) between agents. | Flexible and adaptive workflows, task distribution, dynamic routing. | +| **[GraphWorkflow](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, like software builds. | +| **[MixtureOfAgents (MoA)](https://docs.swarms.world/en/latest/swarms/structs/moa/)** | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving, achieving state-of-the-art performance through collaboration. | +| **[GroupChat](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, brainstorming. | +| **[ForestSwarm](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/)** | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, complex decision-making trees. | +| **[SpreadSheetSwarm](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** | Manages thousands of agents concurrently, tracking tasks and outputs in a structured format. | Massive-scale parallel operations, large-scale data generation and analysis. | +| **[SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** | Universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, unified multi-agent management. | + +----- + +### SequentialWorkflow + +A `SequentialWorkflow` executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. `SequentialWorkflow` is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly. + +```python +from swarms import Agent, SequentialWorkflow + +# Initialize agents for a 3-step process +# 1. Generate an idea +idea_generator = Agent(agent_name="IdeaGenerator", system_prompt="Generate a unique startup idea.", model_name="gpt-4o-mini") +# 2. Validate the idea +validator = Agent(agent_name="Validator", system_prompt="Take this startup idea and analyze its market viability.", model_name="gpt-4o-mini") +# 3. Create a pitch +pitch_creator = Agent(agent_name="PitchCreator", system_prompt="Write a 3-sentence elevator pitch for this validated startup idea.", model_name="gpt-4o-mini") + +# Create the sequential workflow +workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator]) + +# Run the workflow +elevator_pitch = workflow.run() +print(elevator_pitch) +``` + +----- + + +### ConcurrentWorkflow (with `SpreadSheetSwarm`) + +A concurrent workflow runs multiple agents simultaneously. `SpreadSheetSwarm` is a powerful implementation that can manage thousands of concurrent agents and log their outputs to a CSV file. Use this architecture for high-throughput tasks that can be performed in parallel, drastically reducing execution time. + +```python +from swarms import Agent, SpreadSheetSwarm + +# Define a list of tasks (e.g., social media posts to generate) +platforms = ["Twitter", "LinkedIn", "Instagram"] + +# Create an agent for each task +agents = [ + Agent( + agent_name=f"{platform}-Marketer", + system_prompt=f"Generate a real estate marketing post for {platform}.", + model_name="gpt-4o-mini", + ) + for platform in platforms +] + +# Initialize the swarm to run these agents concurrently +swarm = SpreadSheetSwarm( + agents=agents, + autosave_on=True, + save_file_path="marketing_posts.csv", +) + +# Run the swarm with a single, shared task description +property_description = "A beautiful 3-bedroom house in sunny California." +swarm.run(task=f"Generate a post about: {property_description}") +# Check marketing_posts.csv for the results! +``` + +--- + +### AgentRearrange + +Inspired by `einsum`, `AgentRearrange` lets you define complex, non-linear relationships between agents using a simple string-based syntax. [Learn more](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/). This architecture is Perfect for orchestrating dynamic workflows where agents might work in parallel, sequence, or a combination of both. + +```python +from swarms import Agent, AgentRearrange + +# Define agents +researcher = Agent(agent_name="researcher", model_name="gpt-4o-mini") +writer = Agent(agent_name="writer", model_name="gpt-4o-mini") +editor = Agent(agent_name="editor", model_name="gpt-4o-mini") + +# Define a flow: researcher sends work to both writer and editor simultaneously +# This is a one-to-many relationship +flow = "researcher -> writer, editor" + +# Create the rearrangement system +rearrange_system = AgentRearrange( + agents=[researcher, writer, editor], + flow=flow, +) + +# Run the system +# The researcher will generate content, and then both the writer and editor +# will process that content in parallel. +outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.") +print(outputs) +``` + + + + +---- + +### SwarmRouter: The Universal Swarm Orchestrator + +The `SwarmRouter` simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the `swarm_type` parameter. [Read the full documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/) + +This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use `SwarmRouter` to execute the same task using different collaborative strategies. + +```python +from swarms import Agent +from swarms.structs.swarm_router import SwarmRouter, SwarmType + +# Define a few generic agents +writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-4o-mini") +editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-4o-mini") +reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-4o-mini") + +# The agents and task will be the same for all examples +agents = [writer, editor, reviewer] +task = "Write a short story about a robot who discovers music." + +# --- Example 1: SequentialWorkflow --- +# Agents run one after another in a chain: Writer -> Editor -> Reviewer. +print("Running a Sequential Workflow...") +sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents) +sequential_output = sequential_router.run(task) +print(f"Final Sequential Output:\n{sequential_output}\n") + +# --- Example 2: ConcurrentWorkflow --- +# All agents receive the same initial task and run at the same time. +print("Running a Concurrent Workflow...") +concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents) +concurrent_outputs = concurrent_router.run(task) +# This returns a dictionary of each agent's output +for agent_name, output in concurrent_outputs.items(): + print(f"Output from {agent_name}:\n{output}\n") + +# --- Example 3: MixtureOfAgents --- +# All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs. +print("Running a Mixture of Agents Workflow...") +aggregator = Agent( + agent_name="Aggregator", + system_prompt="Combine the story, edits, and review into a final document.", + model_name="gpt-4o-mini" +) +moa_router = SwarmRouter( + swarm_type=SwarmType.MixtureOfAgents, + agents=agents, + aggregator_agent=aggregator, # MoA requires an aggregator +) +aggregated_output = moa_router.run(task) +print(f"Final Aggregated Output:\n{aggregated_output}\n") +``` + + +The `SwarmRouter` is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code. + +------- + +### MixtureOfAgents (MoA) + +The `MixtureOfAgents` architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. [Learn more here](https://docs.swarms.world/en/latest/swarms/examples/moa_example/) + +```python +from swarms import Agent, MixtureOfAgents + +# Define expert agents +financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-4o-mini") +market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-4o-mini") +risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-4o-mini") + +# Define the aggregator agent +aggregator = Agent( + agent_name="InvestmentAdvisor", + system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.", + model_name="gpt-4o-mini" +) + +# Create the MoA swarm +moa_swarm = MixtureOfAgents( + agents=[financial_analyst, market_analyst, risk_analyst], + aggregator_agent=aggregator, +) + +# Run the swarm +recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?") +print(recommendation) +``` + +---- + +### GroupChat + +`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making. + +```python +from swarms import Agent, GroupChat + +# Define agents for a debate +tech_optimist = Agent(agent_name="TechOptimist", system_prompt="Argue for the benefits of AI in society.", model_name="gpt-4o-mini") +tech_critic = Agent(agent_name="TechCritic", system_prompt="Argue against the unchecked advancement of AI.", model_name="gpt-4o-mini") + +# Create the group chat +chat = GroupChat( + agents=[tech_optimist, tech_critic], + max_loops=4, # Limit the number of turns in the conversation +) + +# Run the chat with an initial topic +conversation_history = chat.run( + "Let's discuss the societal impact of artificial intelligence." +) + +# Print the full conversation +for message in conversation_history: + print(f"[{message['agent_name']}]: {message['content']}") +``` + + diff --git a/docs/swarms/agents/index.md b/docs/swarms/agents/index.md new file mode 100644 index 00000000..4b632f1b --- /dev/null +++ b/docs/swarms/agents/index.md @@ -0,0 +1,884 @@ +# Agents Introduction + +The Agent class is the core component of the Swarms framework, designed to create intelligent, autonomous AI agents capable of handling complex tasks through multi-modal processing, tool integration, and structured outputs. This comprehensive guide covers all aspects of the Agent class, from basic setup to advanced features. + +## Table of Contents + +1. [Prerequisites & Installation](#prerequisites--installation) +2. [Basic Agent Configuration](#basic-agent-configuration) +3. [Multi-Modal Capabilities](#multi-modal-capabilities) +4. [Tool Integration](#tool-integration) +5. [Structured Outputs](#structured-outputs) +6. [Advanced Features](#advanced-features) +7. [Best Practices](#best-practices) +8. [Complete Examples](#complete-examples) + +## Prerequisites & Installation + +### System Requirements + +- Python 3.7+ + +- OpenAI API key (for GPT models) + +- Anthropic API key (for Claude models) + +### Installation + +```bash +pip3 install -U swarms +``` + +### Environment Setup + +Create a `.env` file with your API keys: + +```bash +OPENAI_API_KEY="your-openai-api-key" +ANTHROPIC_API_KEY="your-anthropic-api-key" +WORKSPACE_DIR="agent_workspace" +``` + +## Basic Agent Configuration + +### Core Agent Structure + +The Agent class provides a comprehensive set of parameters for customization: + +```python +from swarms import Agent + +# Basic agent initialization +agent = Agent( + agent_name="MyAgent", + agent_description="A specialized AI agent for specific tasks", + system_prompt="You are a helpful assistant...", + model_name="gpt-4o-mini", + max_loops=1, + max_tokens=4096, + temperature=0.7, + output_type="str", + safety_prompt_on=True +) +``` + +### Key Configuration Parameters + +| Parameter | Type | Description | Default | +|-----------|------|-------------|---------| +| `agent_name` | str | Unique identifier for the agent | Required | +| `agent_description` | str | Detailed description of capabilities | Required | +| `system_prompt` | str | Core instructions defining behavior | Required | +| `model_name` | str | AI model to use | "gpt-4o-mini" | +| `max_loops` | int | Maximum execution loops | 1 | +| `max_tokens` | int | Maximum response tokens | 4096 | +| `temperature` | float | Response creativity (0-1) | 0.7 | +| `output_type` | str | Response format type | "str" | +| `multi_modal` | bool | Enable image processing | False | +| `safety_prompt_on` | bool | Enable safety checks | True | + +### Simple Example + +```python +from swarms import Agent + +# Create a basic financial advisor agent +financial_agent = Agent( + agent_name="Financial-Advisor", + agent_description="Personal finance and investment advisor", + system_prompt="""You are an expert financial advisor with deep knowledge of: + - Investment strategies and portfolio management + - Risk assessment and mitigation + - Market analysis and trends + - Financial planning and budgeting + + Provide clear, actionable advice while considering risk tolerance.""", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.3, + output_type="str" +) + +# Run the agent +response = financial_agent.run("What are the best investment strategies for a 30-year-old?") +print(response) +``` + +## Multi-Modal Capabilities + +### Image Processing + +The Agent class supports comprehensive image analysis through vision-enabled models: + +```python +from swarms import Agent + +# Create a vision-enabled agent +vision_agent = Agent( + agent_name="Vision-Analyst", + agent_description="Advanced image analysis and quality control agent", + system_prompt="""You are an expert image analyst capable of: + - Detailed visual inspection and quality assessment + - Object detection and classification + - Scene understanding and context analysis + - Defect identification and reporting + + Provide comprehensive analysis with specific observations.""", + model_name="gpt-4o-mini", # Vision-enabled model + multi_modal=True, # Enable multi-modal processing + max_loops=1, + output_type="str" +) + +# Analyze a single image +response = vision_agent.run( + task="Analyze this image for quality control purposes", + img="path/to/image.jpg" +) + +# Process multiple images +response = vision_agent.run( + task="Compare these images and identify differences", + imgs=["image1.jpg", "image2.jpg", "image3.jpg"], + summarize_multiple_images=True +) +``` + +### Supported Image Formats + +| Format | Description | Max Size | +|--------|-------------|----------| +| JPEG/JPG | Standard compressed format | 20MB | +| PNG | Lossless with transparency | 20MB | +| GIF | Animated (first frame only) | 20MB | +| WebP | Modern efficient format | 20MB | + +### Quality Control Example + +```python +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt + +def security_analysis(danger_level: str) -> str: + """Analyze security danger level and return appropriate response.""" + danger_responses = { + "low": "No immediate danger detected", + "medium": "Moderate security concern identified", + "high": "Critical security threat detected", + None: "No danger level assessment available" + } + return danger_responses.get(danger_level, "Unknown danger level") + +# Quality control agent with tool integration +quality_agent = Agent( + agent_name="Quality-Control-Agent", + agent_description="Advanced quality control and security analysis agent", + system_prompt=f""" + {Quality_Control_Agent_Prompt} + + You have access to security analysis tools. When analyzing images: + 1. Identify potential safety hazards + 2. Assess quality standards compliance + 3. Determine appropriate danger levels (low, medium, high) + 4. Use the security_analysis function for threat assessment + """, + model_name="gpt-4o-mini", + multi_modal=True, + max_loops=1, + tools=[security_analysis] +) + +# Analyze factory image +response = quality_agent.run( + task="Analyze this factory image for safety and quality issues", + img="factory_floor.jpg" +) +``` + +## Tool Integration + +### Creating Custom Tools + +Tools are Python functions that extend your agent's capabilities: + +```python +import json +import requests +from typing import Optional, Dict, Any + +def get_weather_data(city: str, country: Optional[str] = None) -> str: + """ + Get current weather data for a specified city. + + Args: + city (str): The city name + country (Optional[str]): Country code (e.g., 'US', 'UK') + + Returns: + str: JSON formatted weather data + + Example: + >>> weather = get_weather_data("San Francisco", "US") + >>> print(weather) + {"temperature": 18, "condition": "partly cloudy", ...} + """ + try: + # API call logic here + weather_data = { + "city": city, + "country": country, + "temperature": 18, + "condition": "partly cloudy", + "humidity": 65, + "wind_speed": 12 + } + return json.dumps(weather_data, indent=2) + + except Exception as e: + return json.dumps({"error": f"Weather API error: {str(e)}"}) + +def calculate_portfolio_metrics(prices: list, weights: list) -> str: + """ + Calculate portfolio performance metrics. + + Args: + prices (list): List of asset prices + weights (list): List of portfolio weights + + Returns: + str: JSON formatted portfolio metrics + """ + try: + # Portfolio calculation logic + portfolio_value = sum(p * w for p, w in zip(prices, weights)) + metrics = { + "total_value": portfolio_value, + "weighted_average": portfolio_value / sum(weights), + "asset_count": len(prices) + } + return json.dumps(metrics, indent=2) + + except Exception as e: + return json.dumps({"error": f"Calculation error: {str(e)}"}) +``` + +### Tool Integration Example + +```python +from swarms import Agent + +# Create agent with custom tools +multi_tool_agent = Agent( + agent_name="Multi-Tool-Assistant", + agent_description="Versatile assistant with weather and financial tools", + system_prompt="""You are a versatile assistant with access to: + - Weather data retrieval for any city + - Portfolio analysis and financial calculations + + Use these tools to provide comprehensive assistance.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_weather_data, calculate_portfolio_metrics] +) + +# Use the agent with tools +response = multi_tool_agent.run( + "What's the weather in New York and calculate metrics for a portfolio with prices [100, 150, 200] and weights [0.3, 0.4, 0.3]?" +) +``` + +### API Integration Tools + +```python +import requests +import json +from typing import List + +def get_cryptocurrency_price(coin_id: str, vs_currency: str = "usd") -> str: + """Get current cryptocurrency price from CoinGecko API.""" + try: + url = "https://api.coingecko.com/api/v3/simple/price" + params = { + "ids": coin_id, + "vs_currencies": vs_currency, + "include_market_cap": True, + "include_24hr_vol": True, + "include_24hr_change": True + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) + + except Exception as e: + return json.dumps({"error": f"API error: {str(e)}"}) + +def get_top_cryptocurrencies(limit: int = 10) -> str: + """Get top cryptocurrencies by market cap.""" + try: + url = "https://api.coingecko.com/api/v3/coins/markets" + params = { + "vs_currency": "usd", + "order": "market_cap_desc", + "per_page": limit, + "page": 1 + } + + response = requests.get(url, params=params, timeout=10) + response.raise_for_status() + return json.dumps(response.json(), indent=2) + + except Exception as e: + return json.dumps({"error": f"API error: {str(e)}"}) + +# Crypto analysis agent +crypto_agent = Agent( + agent_name="Crypto-Analysis-Agent", + agent_description="Cryptocurrency market analysis and price tracking agent", + system_prompt="""You are a cryptocurrency analysis expert with access to: + - Real-time price data for any cryptocurrency + - Market capitalization rankings + - Trading volume and price change data + + Provide insightful market analysis and investment guidance.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_cryptocurrency_price, get_top_cryptocurrencies] +) + +# Analyze crypto market +response = crypto_agent.run("Analyze the current Bitcoin price and show me the top 5 cryptocurrencies") +``` + +## Structured Outputs + +### Function Schema Definition + +Define structured outputs using OpenAI's function calling format: + +```python +from swarms import Agent + +# Define function schemas for structured outputs +stock_analysis_schema = { + "type": "function", + "function": { + "name": "analyze_stock_performance", + "description": "Analyze stock performance with detailed metrics", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "Stock ticker symbol (e.g., AAPL, GOOGL)" + }, + "analysis_type": { + "type": "string", + "enum": ["technical", "fundamental", "comprehensive"], + "description": "Type of analysis to perform" + }, + "time_period": { + "type": "string", + "enum": ["1d", "1w", "1m", "3m", "1y"], + "description": "Time period for analysis" + }, + "metrics": { + "type": "array", + "items": { + "type": "string", + "enum": ["price", "volume", "pe_ratio", "market_cap", "volatility"] + }, + "description": "Metrics to include in analysis" + } + }, + "required": ["ticker", "analysis_type"] + } + } +} + +portfolio_optimization_schema = { + "type": "function", + "function": { + "name": "optimize_portfolio", + "description": "Optimize portfolio allocation based on risk and return", + "parameters": { + "type": "object", + "properties": { + "assets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "symbol": {"type": "string"}, + "current_weight": {"type": "number"}, + "expected_return": {"type": "number"}, + "risk_level": {"type": "string", "enum": ["low", "medium", "high"]} + }, + "required": ["symbol", "current_weight"] + } + }, + "risk_tolerance": { + "type": "string", + "enum": ["conservative", "moderate", "aggressive"] + }, + "investment_horizon": { + "type": "integer", + "minimum": 1, + "maximum": 30, + "description": "Investment time horizon in years" + } + }, + "required": ["assets", "risk_tolerance"] + } + } +} + +# Create agent with structured outputs +structured_agent = Agent( + agent_name="Structured-Financial-Agent", + agent_description="Financial analysis agent with structured output capabilities", + system_prompt="""You are a financial analysis expert that provides structured outputs. + Use the provided function schemas to format your responses consistently.""", + model_name="gpt-4o-mini", + max_loops=1, + tools_list_dictionary=[stock_analysis_schema, portfolio_optimization_schema] +) + +# Generate structured analysis +response = structured_agent.run( + "Analyze Apple stock (AAPL) performance with comprehensive analysis for the last 3 months" +) +``` + +## Advanced Features + +### Dynamic Temperature Control + +```python +from swarms import Agent + +# Agent with dynamic temperature adjustment +adaptive_agent = Agent( + agent_name="Adaptive-Response-Agent", + agent_description="Agent that adjusts response creativity based on context", + system_prompt="You are an adaptive AI that adjusts your response style based on the task complexity.", + model_name="gpt-4o-mini", + dynamic_temperature_enabled=True, # Enable adaptive temperature + max_loops=1, + output_type="str" +) +``` + +### Output Type Configurations + +```python +# Different output type examples +json_agent = Agent( + agent_name="JSON-Agent", + system_prompt="Always respond in valid JSON format", + output_type="json" +) + +streaming_agent = Agent( + agent_name="Streaming-Agent", + system_prompt="Provide detailed streaming responses", + output_type="str-all-except-first" +) + +final_only_agent = Agent( + agent_name="Final-Only-Agent", + system_prompt="Provide only the final result", + output_type="final" +) +``` + +### Safety and Content Filtering + +```python +from swarms import Agent + +# Agent with enhanced safety features +safe_agent = Agent( + agent_name="Safe-Agent", + agent_description="Agent with comprehensive safety measures", + system_prompt="You are a helpful, harmless, and honest AI assistant.", + model_name="gpt-4o-mini", + safety_prompt_on=True, # Enable safety prompts + max_loops=1, + temperature=0.3 # Lower temperature for more consistent, safe responses +) +``` + +## Best Practices + +### Error Handling and Robustness + +```python +import logging +from swarms import Agent + +# Configure logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +def robust_agent_execution(agent, task, max_retries=3): + """Execute agent with retry logic and error handling.""" + for attempt in range(max_retries): + try: + response = agent.run(task) + logger.info(f"Agent execution successful on attempt {attempt + 1}") + return response + except Exception as e: + logger.error(f"Attempt {attempt + 1} failed: {str(e)}") + if attempt == max_retries - 1: + raise + time.sleep(2 ** attempt) # Exponential backoff + + return None + +# Example usage +try: + result = robust_agent_execution(agent, "Analyze market trends") + print(result) +except Exception as e: + print(f"Agent execution failed: {e}") +``` + +### Performance Optimization + +```python +from swarms import Agent +import time + +# Optimized agent configuration +optimized_agent = Agent( + agent_name="Optimized-Agent", + agent_description="Performance-optimized agent configuration", + system_prompt="You are an efficient AI assistant optimized for performance.", + model_name="gpt-4o-mini", # Faster model + max_loops=1, # Minimize loops + max_tokens=2048, # Reasonable token limit + temperature=0.5, # Balanced creativity + output_type="str" +) + +# Batch processing example +def process_tasks_batch(agent, tasks, batch_size=5): + """Process multiple tasks efficiently.""" + results = [] + for i in range(0, len(tasks), batch_size): + batch = tasks[i:i + batch_size] + batch_results = [] + + for task in batch: + start_time = time.time() + result = agent.run(task) + execution_time = time.time() - start_time + + batch_results.append({ + "task": task, + "result": result, + "execution_time": execution_time + }) + + results.extend(batch_results) + time.sleep(1) # Rate limiting + + return results +``` + +## Complete Examples + +### Multi-Modal Quality Control System + +```python +from swarms import Agent +from swarms.prompts.logistics import Quality_Control_Agent_Prompt + +def security_analysis(danger_level: str) -> str: + """Analyze security danger level and return appropriate response.""" + responses = { + "low": "✅ No immediate danger detected - Safe to proceed", + "medium": "⚠️ Moderate security concern - Requires attention", + "high": "🚨 Critical security threat - Immediate action required", + None: "❓ No danger level assessment available" + } + return responses.get(danger_level, "Unknown danger level") + +def quality_assessment(quality_score: int) -> str: + """Assess quality based on numerical score (1-10).""" + if quality_score >= 8: + return "✅ Excellent quality - Meets all standards" + elif quality_score >= 6: + return "⚠️ Good quality - Minor improvements needed" + elif quality_score >= 4: + return "❌ Poor quality - Significant issues identified" + else: + return "🚨 Critical quality failure - Immediate attention required" + +# Advanced quality control agent +quality_control_system = Agent( + agent_name="Advanced-Quality-Control-System", + agent_description="Comprehensive quality control and security analysis system", + system_prompt=f""" + {Quality_Control_Agent_Prompt} + + You are an advanced quality control system with the following capabilities: + + 1. Visual Inspection: Analyze images for defects, compliance, and safety + 2. Security Assessment: Identify potential security threats and hazards + 3. Quality Scoring: Provide numerical quality ratings (1-10 scale) + 4. Detailed Reporting: Generate comprehensive analysis reports + + When analyzing images: + - Identify specific defects or issues + - Assess compliance with safety standards + - Determine appropriate danger levels (low, medium, high) + - Provide quality scores and recommendations + - Use available tools for detailed analysis + + Always provide specific, actionable feedback. + """, + model_name="gpt-4o-mini", + multi_modal=True, + max_loops=1, + tools=[security_analysis, quality_assessment], + output_type="str" +) + +# Process factory images +factory_images = ["factory_floor.jpg", "assembly_line.jpg", "safety_equipment.jpg"] + +for image in factory_images: + print(f"\n--- Analyzing {image} ---") + response = quality_control_system.run( + task=f"Perform comprehensive quality control analysis of this image. Assess safety, quality, and provide specific recommendations.", + img=image + ) + print(response) +``` + +### Advanced Financial Analysis Agent + +```python +from swarms import Agent +import json +import requests + +def get_market_data(symbol: str, period: str = "1y") -> str: + """Get comprehensive market data for a symbol.""" + # Simulated market data (replace with real API) + market_data = { + "symbol": symbol, + "current_price": 150.25, + "change_percent": 2.5, + "volume": 1000000, + "market_cap": 2500000000, + "pe_ratio": 25.5, + "dividend_yield": 1.8, + "52_week_high": 180.50, + "52_week_low": 120.30 + } + return json.dumps(market_data, indent=2) + +def calculate_risk_metrics(prices: list, benchmark_prices: list) -> str: + """Calculate risk metrics for a portfolio.""" + import numpy as np + + try: + returns = np.diff(prices) / prices[:-1] + benchmark_returns = np.diff(benchmark_prices) / benchmark_prices[:-1] + + volatility = np.std(returns) * np.sqrt(252) # Annualized + sharpe_ratio = (np.mean(returns) / np.std(returns)) * np.sqrt(252) + max_drawdown = np.max(np.maximum.accumulate(prices) - prices) / np.max(prices) + + beta = np.cov(returns, benchmark_returns)[0, 1] / np.var(benchmark_returns) + + risk_metrics = { + "volatility": float(volatility), + "sharpe_ratio": float(sharpe_ratio), + "max_drawdown": float(max_drawdown), + "beta": float(beta) + } + + return json.dumps(risk_metrics, indent=2) + + except Exception as e: + return json.dumps({"error": f"Risk calculation error: {str(e)}"}) + +# Financial analysis schemas +financial_analysis_schema = { + "type": "function", + "function": { + "name": "comprehensive_financial_analysis", + "description": "Perform comprehensive financial analysis with structured output", + "parameters": { + "type": "object", + "properties": { + "analysis_summary": { + "type": "object", + "properties": { + "overall_rating": {"type": "string", "enum": ["buy", "hold", "sell"]}, + "confidence_level": {"type": "number", "minimum": 0, "maximum": 100}, + "key_strengths": {"type": "array", "items": {"type": "string"}}, + "key_concerns": {"type": "array", "items": {"type": "string"}}, + "price_target": {"type": "number"}, + "risk_level": {"type": "string", "enum": ["low", "medium", "high"]} + } + }, + "technical_analysis": { + "type": "object", + "properties": { + "trend_direction": {"type": "string", "enum": ["bullish", "bearish", "neutral"]}, + "support_levels": {"type": "array", "items": {"type": "number"}}, + "resistance_levels": {"type": "array", "items": {"type": "number"}}, + "momentum_indicators": {"type": "array", "items": {"type": "string"}} + } + } + }, + "required": ["analysis_summary", "technical_analysis"] + } + } +} + +# Advanced financial agent +financial_analyst = Agent( + agent_name="Advanced-Financial-Analyst", + agent_description="Comprehensive financial analysis and investment advisory agent", + system_prompt="""You are an expert financial analyst with advanced capabilities in: + + - Fundamental analysis and valuation + - Technical analysis and chart patterns + - Risk assessment and portfolio optimization + - Market sentiment analysis + - Economic indicator interpretation + + Your analysis should be: + - Data-driven and objective + - Risk-aware and practical + - Clearly structured and actionable + - Compliant with financial regulations + + Use available tools to gather market data and calculate risk metrics. + Provide structured outputs using the defined schemas.""", + model_name="gpt-4o-mini", + max_loops=1, + tools=[get_market_data, calculate_risk_metrics], + tools_list_dictionary=[financial_analysis_schema], + output_type="json" +) + +# Comprehensive financial analysis +analysis_response = financial_analyst.run( + "Perform a comprehensive analysis of Apple Inc. (AAPL) including technical and fundamental analysis with structured recommendations" +) + +print(json.dumps(json.loads(analysis_response), indent=2)) +``` + +### Multi-Agent Collaboration System + +```python +from swarms import Agent +import json + +# Specialized agents for different tasks +research_agent = Agent( + agent_name="Research-Specialist", + agent_description="Market research and data analysis specialist", + system_prompt="You are a market research expert specializing in data collection and analysis.", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.3 +) + +strategy_agent = Agent( + agent_name="Strategy-Advisor", + agent_description="Strategic planning and recommendation specialist", + system_prompt="You are a strategic advisor providing high-level recommendations based on research.", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.5 +) + +execution_agent = Agent( + agent_name="Execution-Planner", + agent_description="Implementation and execution planning specialist", + system_prompt="You are an execution expert creating detailed implementation plans.", + model_name="gpt-4o-mini", + max_loops=1, + temperature=0.4 +) + +def collaborative_analysis(topic: str): + """Perform collaborative analysis using multiple specialized agents.""" + + # Step 1: Research Phase + research_task = f"Conduct comprehensive research on {topic}. Provide key findings, market data, and trends." + research_results = research_agent.run(research_task) + + # Step 2: Strategy Phase + strategy_task = f"Based on this research: {research_results}\n\nDevelop strategic recommendations for {topic}." + strategy_results = strategy_agent.run(strategy_task) + + # Step 3: Execution Phase + execution_task = f"Create a detailed implementation plan based on:\nResearch: {research_results}\nStrategy: {strategy_results}" + execution_results = execution_agent.run(execution_task) + + return { + "research": research_results, + "strategy": strategy_results, + "execution": execution_results + } + +# Example: Collaborative investment analysis +investment_analysis = collaborative_analysis("renewable energy sector investment opportunities") + +for phase, results in investment_analysis.items(): + print(f"\n=== {phase.upper()} PHASE ===") + print(results) +``` + +## Support and Resources + +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! + +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | + +### Getting Help + +If you encounter issues or need assistance: + +1. **Check the Documentation**: Start with the official docs for comprehensive guides +2. **Search Issues**: Look through existing GitHub issues for similar problems +3. **Join Discord**: Get real-time help from the community +4. **Create an Issue**: Report bugs or request features on GitHub +5. **Follow Updates**: Stay informed about new releases and improvements + +### Contributing + +We welcome contributions! Here's how to get involved: + +- **Report Bugs**: Help us improve by reporting issues + +- **Suggest Features**: Share your ideas for new capabilities + +- **Submit Code**: Contribute improvements and new features + +- **Improve Documentation**: Help make our docs better + +- **Share Examples**: Show how you're using Swarms in your projects + +--- + +*This guide covers the essential aspects of the Swarms Agent class. For the most up-to-date information and advanced features, please refer to the official documentation and community resources.* \ No newline at end of file diff --git a/docs/swarms/structs/interactive_groupchat.md b/docs/swarms/structs/interactive_groupchat.md index 7dbfae9c..32008016 100644 --- a/docs/swarms/structs/interactive_groupchat.md +++ b/docs/swarms/structs/interactive_groupchat.md @@ -4,23 +4,20 @@ The InteractiveGroupChat is a sophisticated multi-agent system that enables inte ## Features -- **@mentions Support**: Direct tasks to specific agents using @agent_name syntax - -- **Multi-Agent Collaboration**: Multiple mentioned agents can see and respond to each other's tasks - -- **Enhanced Collaborative Prompts**: Agents are trained to acknowledge, build upon, and synthesize each other's responses - -- **Speaker Functions**: Control the order in which agents respond (round robin, random, priority, custom) - -- **Dynamic Speaker Management**: Change speaker functions and priorities during runtime - -- **Callable Function Support**: Supports both Agent instances and callable functions as chat participants - -- **Comprehensive Error Handling**: Custom error classes for different scenarios - -- **Conversation History**: Maintains a complete history of the conversation - -- **Flexible Output Formatting**: Configurable output format for conversation history +| Feature | Description | +|---------|-------------| +| **@mentions Support** | Direct tasks to specific agents using @agent_name syntax | +| **Multi-Agent Collaboration** | Multiple mentioned agents can see and respond to each other's tasks | +| **Enhanced Collaborative Prompts** | Agents are trained to acknowledge, build upon, and synthesize each other's responses | +| **Speaker Functions** | Control the order in which agents respond (round robin, random, priority, custom) | +| **Dynamic Speaker Management** | Change speaker functions and priorities during runtime | +| **Random Dynamic Speaker** | Advanced speaker function that follows @mentions in agent responses | +| **Parallel and Sequential Strategies** | Support for both parallel and sequential agent execution | +| **Callable Function Support** | Supports both Agent instances and callable functions as chat participants | +| **Comprehensive Error Handling** | Custom error classes for different scenarios | +| **Conversation History** | Maintains a complete history of the conversation | +| **Flexible Output Formatting** | Configurable output format for conversation history | +| **Interactive Terminal Mode** | Full REPL interface for real-time chat with agents | ## Installation @@ -46,7 +43,7 @@ Initializes a new InteractiveGroupChat instance with the specified configuration | `max_loops` | int | Maximum conversation turns | 1 | | `output_type` | str | Type of output format | "string" | | `interactive` | bool | Whether to enable interactive mode | False | -| `speaker_function` | Callable | Function to determine speaking order | round_robin_speaker | +| `speaker_function` | Union[str, Callable] | Function to determine speaking order | round_robin_speaker | | `speaker_state` | dict | Initial state for speaker function | {"current_index": 0} | **Example:** @@ -90,6 +87,8 @@ Processes a task and gets responses from mentioned agents. This is the main meth **Arguments:** - `task` (str): The input task containing @mentions to agents +- `img` (Optional[str]): Optional image for the task +- `imgs` (Optional[List[str]]): Optional list of images for the task **Returns:** @@ -104,6 +103,10 @@ print(response) # Multiple agent collaboration response = chat.run("@FinancialAdvisor and @TaxExpert, how can I minimize taxes on my investments?") print(response) + +# With image input +response = chat.run("@FinancialAdvisor analyze this chart", img="chart.png") +print(response) ``` ### Start Interactive Session (`start_interactive_session`) @@ -114,6 +117,13 @@ Starts an interactive terminal session for real-time chat with agents. This crea **Arguments:** None +**Features:** +- Real-time chat with agents using @mentions +- View available agents and their descriptions +- Change speaker functions during the session +- Built-in help system +- Graceful exit with 'exit' or 'quit' commands + **Example:** ```python @@ -127,6 +137,119 @@ chat = InteractiveGroupChat( chat.start_interactive_session() ``` +**Interactive Session Commands:** +- `@agent_name message` - Mention specific agents +- `help` or `?` - Show help information +- `speaker` - Change speaker function +- `exit` or `quit` - End the session + +### Set Speaker Function (`set_speaker_function`) + +**Description:** + +Dynamically changes the speaker function and optional state during runtime. + +**Arguments:** + +- `speaker_function` (Union[str, Callable]): Function that determines speaking order + - String options: "round-robin-speaker", "random-speaker", "priority-speaker", "random-dynamic-speaker" + - Callable: Custom function that takes (agents: List[str], **kwargs) -> str +- `speaker_state` (dict, optional): State for the speaker function + +**Example:** +```python +from swarms.structs.interactive_groupchat import random_speaker, priority_speaker + +# Change to random speaker function +chat.set_speaker_function(random_speaker) + +# Change to priority speaker with custom priorities +chat.set_speaker_function(priority_speaker, {"financial_advisor": 3, "tax_expert": 2}) + +# Change to random dynamic speaker +chat.set_speaker_function("random-dynamic-speaker") +``` + +### Get Available Speaker Functions (`get_available_speaker_functions`) + +**Description:** + +Returns a list of all available built-in speaker function names. + +**Arguments:** +None + +**Returns:** + +- List[str]: List of available speaker function names + +**Example:** +```python +available_functions = chat.get_available_speaker_functions() +print(available_functions) +# Output: ['round-robin-speaker', 'random-speaker', 'priority-speaker', 'random-dynamic-speaker'] +``` + +### Get Current Speaker Function (`get_current_speaker_function`) + +**Description:** + +Returns the name of the currently active speaker function. + +**Arguments:** +None + +**Returns:** + +- str: Name of the current speaker function, or "custom" if it's a custom function + +**Example:** +```python +current_function = chat.get_current_speaker_function() +print(current_function) # Output: "round-robin-speaker" +``` + +### Set Priorities (`set_priorities`) + +**Description:** + +Sets agent priorities for priority-based speaking order. + +**Arguments:** + +- `priorities` (dict): Dictionary mapping agent names to priority weights + +**Example:** +```python +# Set agent priorities (higher numbers = higher priority) +chat.set_priorities({ + "financial_advisor": 5, + "tax_expert": 3, + "investment_analyst": 1 +}) +``` + +### Set Dynamic Strategy (`set_dynamic_strategy`) + +**Description:** + +Sets the strategy for the random-dynamic-speaker function. + +**Arguments:** + +- `strategy` (str): Either "sequential" or "parallel" + - "sequential": Process one agent at a time based on @mentions + - "parallel": Process all mentioned agents simultaneously + +**Example:** +```python +# Set to sequential strategy (one agent at a time) +chat.set_dynamic_strategy("sequential") + +# Set to parallel strategy (all mentioned agents respond simultaneously) +chat.set_dynamic_strategy("parallel") +``` + ### Extract Mentions (`_extract_mentions`) **Description:** @@ -207,49 +330,6 @@ chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert]) # Each agent now knows about the other participants and how to collaborate effectively ``` -### Set Speaker Function (`set_speaker_function`) - -**Description:** - -Dynamically changes the speaker function and optional state during runtime. - -**Arguments:** - -- `speaker_function` (Callable): Function that determines speaking order - -- `speaker_state` (dict, optional): State for the speaker function - -**Example:** -```python -from swarms.structs.interactive_groupchat import random_speaker, priority_speaker - -# Change to random speaker function -chat.set_speaker_function(random_speaker) - -# Change to priority speaker with custom priorities -chat.set_speaker_function(priority_speaker, {"financial_advisor": 3, "tax_expert": 2}) -``` - -### Set Priorities (`set_priorities`) - -**Description:** - -Sets agent priorities for priority-based speaking order. - -**Arguments:** - -- `priorities` (dict): Dictionary mapping agent names to priority weights - -**Example:** -```python -# Set agent priorities (higher numbers = higher priority) -chat.set_priorities({ - "financial_advisor": 5, - "tax_expert": 3, - "investment_analyst": 1 -}) -``` - ### Get Speaking Order (`_get_speaking_order`) **Description:** @@ -345,6 +425,41 @@ chat = InteractiveGroupChat( - Good for hierarchical teams or expert-led discussions +#### Random Dynamic Speaker (`random_dynamic_speaker`) + +Advanced speaker function that follows @mentions in agent responses, enabling dynamic conversation flow. + +```python +from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker + +chat = InteractiveGroupChat( + agents=agents, + speaker_function=random_dynamic_speaker, + speaker_state={"strategy": "parallel"}, # or "sequential" + interactive=False, +) +``` + +**Behavior:** + +- **First Call**: Randomly selects an agent to start the conversation +- **Subsequent Calls**: Extracts @mentions from the previous agent's response and selects the next speaker(s) +- **Two Strategies**: + - **Sequential**: Processes one agent at a time based on @mentions + - **Parallel**: Processes all mentioned agents simultaneously + +**Example Dynamic Flow:** +```python +# Agent A responds: "I think @AgentB should analyze this data and @AgentC should review the methodology" +# With sequential strategy: Agent B speaks next +# With parallel strategy: Both Agent B and Agent C speak simultaneously +``` + +**Use Cases:** +- Complex problem-solving where agents need to delegate to specific experts +- Dynamic workflows where the conversation flow depends on agent responses +- Collaborative decision-making processes + ### Custom Speaker Functions You can create your own speaker functions to implement custom logic: @@ -394,6 +509,10 @@ chat.set_speaker_function(random_speaker) # Change to priority with custom priorities chat.set_priorities({"financial_advisor": 5, "tax_expert": 3, "analyst": 1}) chat.set_speaker_function(priority_speaker) + +# Change to dynamic speaker with parallel strategy +chat.set_speaker_function("random-dynamic-speaker") +chat.set_dynamic_strategy("parallel") ``` ## Enhanced Collaborative Behavior @@ -518,6 +637,8 @@ except InvalidSpeakerFunctionError as e: | Agent Naming | Use clear, unique names for agents to avoid confusion | `financial_advisor`, `tax_expert` | | Task Format | Always use @mentions to direct tasks to specific agents | `@financial_advisor What's your investment advice?` | | Speaker Functions | Choose appropriate speaker functions for your use case | Round robin for fairness, priority for expert-led discussions | +| Dynamic Speaker | Use random-dynamic-speaker for complex workflows with delegation | When agents need to call on specific experts | +| Strategy Selection | Choose sequential for focused discussions, parallel for brainstorming | Sequential for analysis, parallel for idea generation | | Collaborative Design | Design agents with complementary expertise for better collaboration | Analyst + Researcher + Strategist | | Error Handling | Implement proper error handling for various scenarios | `try/except` blocks for `AgentNotFoundError` | | Context Management | Be aware that agents can see the full conversation history | Monitor conversation length and relevance | @@ -614,6 +735,53 @@ response = chat.run(task) print(response) ``` +### Dynamic Speaker Function with Delegation + +```python +from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker + +# Create specialized medical agents +cardiologist = Agent( + agent_name="cardiologist", + system_prompt="You are a cardiologist specializing in heart conditions.", + llm="gpt-4", +) + +oncologist = Agent( + agent_name="oncologist", + system_prompt="You are an oncologist specializing in cancer treatment.", + llm="gpt-4", +) + +endocrinologist = Agent( + agent_name="endocrinologist", + system_prompt="You are an endocrinologist specializing in hormone disorders.", + llm="gpt-4", +) + +# Create dynamic group chat +chat = InteractiveGroupChat( + name="Medical Panel Discussion", + description="A collaborative panel of medical specialists", + agents=[cardiologist, oncologist, endocrinologist], + speaker_function=random_dynamic_speaker, + speaker_state={"strategy": "sequential"}, + interactive=False, +) + +# Complex medical case with dynamic delegation +case = """CASE PRESENTATION: +A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of +stage 3 colon cancer presents with chest pain and shortness of breath. +ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) +and signs of infection (WBC 15,000, CRP elevated). + +@cardiologist @oncologist @endocrinologist please provide your assessment and treatment recommendations.""" + +response = chat.run(case) +print(response) +``` + ### Dynamic Speaker Function Changes ```python @@ -621,7 +789,8 @@ from swarms.structs.interactive_groupchat import ( InteractiveGroupChat, round_robin_speaker, random_speaker, - priority_speaker + priority_speaker, + random_dynamic_speaker ) # Create brainstorming agents @@ -647,10 +816,16 @@ chat.set_speaker_function(priority_speaker) task2 = "Now let's analyze the feasibility of these ideas. @creative @analytical @practical" response2 = chat.run(task2) -# Phase 3: Implementation (round robin for equal input) -chat.set_speaker_function(round_robin_speaker) -task3 = "Finally, let's plan implementation. @creative @analytical @practical" +# Phase 3: Dynamic delegation (agents mention each other) +chat.set_speaker_function(random_dynamic_speaker) +chat.set_dynamic_strategy("sequential") +task3 = "Let's plan implementation with dynamic delegation. @creative @analytical @practical" response3 = chat.run(task3) + +# Phase 4: Final synthesis (round robin for equal input) +chat.set_speaker_function(round_robin_speaker) +task4 = "Finally, let's synthesize our findings. @creative @analytical @practical" +response4 = chat.run(task4) ``` ### Custom Speaker Function @@ -726,38 +901,47 @@ chat.start_interactive_session() 3. **Better Delegation**: Agents naturally delegate to appropriate experts 4. **Enhanced Problem Solving**: Complex problems are addressed systematically 5. **More Natural Interactions**: Agents respond like real team members +6. **Dynamic Workflows**: Conversation flow adapts based on agent responses +7. **Flexible Execution**: Support for both sequential and parallel processing ### Use Cases -| Use Case Category | Specific Use Case | Agent Team Composition | -|------------------|-------------------|----------------------| -| **Business Analysis and Strategy** | Data Analysis | Analyst + Researcher + Strategist | -| | Market Research | Multiple experts analyzing different aspects | -| | Strategic Planning | Expert-led discussions with collaborative input | -| **Product Development** | Requirements Gathering | Product Manager + Developer + Designer | -| | Technical Architecture | Senior + Junior developers with different expertise | -| | User Experience | UX Designer + Product Manager + Developer | -| **Research and Development** | Scientific Research | Multiple researchers with different specializations | -| | Literature Review | Different experts reviewing various aspects | -| | Experimental Design | Statistician + Domain Expert + Methodologist | -| **Creative Projects** | Content Creation | Writer + Editor + Designer | -| | Marketing Campaigns | Creative + Analyst + Strategist | -| | Design Projects | Designer + Developer + Product Manager | -| **Problem Solving** | Troubleshooting | Technical + Business + User perspective experts | -| | Crisis Management | Emergency + Communication + Technical teams | -| | Decision Making | Executive + Analyst + Specialist | +| Use Case Category | Specific Use Case | Agent Team Composition | Recommended Speaker Function | +|------------------|-------------------|----------------------|------------------------------| +| **Business Analysis and Strategy** | Data Analysis | Analyst + Researcher + Strategist | Round Robin | +| | Market Research | Multiple experts analyzing different aspects | Random Dynamic | +| | Strategic Planning | Expert-led discussions with collaborative input | Priority | +| **Product Development** | Requirements Gathering | Product Manager + Developer + Designer | Round Robin | +| | Technical Architecture | Senior + Junior developers with different expertise | Priority | +| | User Experience | UX Designer + Product Manager + Developer | Random Dynamic | +| **Research and Development** | Scientific Research | Multiple researchers with different specializations | Random Dynamic | +| | Literature Review | Different experts reviewing various aspects | Round Robin | +| | Experimental Design | Statistician + Domain Expert + Methodologist | Priority | +| **Creative Projects** | Content Creation | Writer + Editor + Designer | Random | +| | Marketing Campaigns | Creative + Analyst + Strategist | Random Dynamic | +| | Design Projects | Designer + Developer + Product Manager | Round Robin | +| **Problem Solving** | Troubleshooting | Technical + Business + User perspective experts | Priority | +| | Crisis Management | Emergency + Communication + Technical teams | Priority | +| | Decision Making | Executive + Analyst + Specialist | Priority | +| **Medical Consultation** | Complex Cases | Multiple specialists (Cardiologist + Oncologist + Endocrinologist) | Random Dynamic | +| | Treatment Planning | Senior + Junior doctors with different expertise | Priority | +| | Research Review | Multiple researchers reviewing different aspects | Round Robin | ### Speaker Function Selection Guide -| Use Case | Recommended Speaker Function | Reasoning | -|----------|------------------------------|-----------| -| Team Meetings | Round Robin | Ensures equal participation | -| Brainstorming | Random | Prevents bias and encourages creativity | -| Expert Consultation | Priority | Senior experts speak first | -| Problem Solving | Priority | Most relevant experts prioritize | -| Creative Sessions | Random | Encourages diverse perspectives | -| Decision Making | Priority | Decision makers speak first | -| Research Review | Round Robin | Equal contribution from all reviewers | +| Use Case | Recommended Speaker Function | Strategy | Reasoning | +|----------|------------------------------|----------|-----------| +| Team Meetings | Round Robin | N/A | Ensures equal participation | +| Brainstorming | Random | N/A | Prevents bias and encourages creativity | +| Expert Consultation | Priority | N/A | Senior experts speak first | +| Problem Solving | Priority | N/A | Most relevant experts prioritize | +| Creative Sessions | Random | N/A | Encourages diverse perspectives | +| Decision Making | Priority | N/A | Decision makers speak first | +| Research Review | Round Robin | N/A | Equal contribution from all reviewers | +| Complex Workflows | Random Dynamic | Sequential | Follows natural conversation flow | +| Parallel Analysis | Random Dynamic | Parallel | Multiple agents work simultaneously | +| Medical Panels | Random Dynamic | Sequential | Specialists delegate to relevant experts | +| Technical Architecture | Random Dynamic | Sequential | Senior architects guide the discussion | ## Contributing diff --git a/docs/swarms_cloud/quickstart.md b/docs/swarms_cloud/quickstart.md new file mode 100644 index 00000000..37a3a685 --- /dev/null +++ b/docs/swarms_cloud/quickstart.md @@ -0,0 +1,1165 @@ + +# Swarms Quickstart Guide + +This guide will help you get started with both single agent and multi-agent functionalities in Swarms API. + +## Prerequisites + +!!! info "Requirements" + + - Python 3.7+ + - API key from [Swarms Platform](https://swarms.world/platform/api-keys) + - `requests` library for Python + - `axios` for TypeScript/JavaScript + - `curl` for shell commands + +## Installation + +=== "pip" + + ```bash + pip install requests python-dotenv + ``` + +=== "npm" + + ```bash + npm install axios dotenv + ``` + +## Authentication + +!!! warning "API Key Security" + + Never hardcode your API key in your code. Always use environment variables or secure configuration management. + +The API is accessible through two base URLs: + +- Production: `https://api.swarms.world` +- Alternative: `https://swarms-api-285321057562.us-east1.run.app` + +## Single Agent Usage + +### Health Check + +=== "Python" + + ```python linenums="1" title="health_check.py" + import os + import requests + from dotenv import load_dotenv + + load_dotenv() + API_KEY = os.getenv("SWARMS_API_KEY") + BASE_URL = "https://api.swarms.world" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } + + response = requests.get(f"{BASE_URL}/health", headers=headers) + print(response.json()) + ``` + +=== "cURL" + + ```bash title="health_check.sh" + curl -X GET "https://api.swarms.world/health" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="health_check.ts" + import axios from 'axios'; + import * as dotenv from 'dotenv'; + + dotenv.config(); + const API_KEY = process.env.SWARMS_API_KEY; + const BASE_URL = 'https://api.swarms.world'; + + async function checkHealth() { + try { + const response = await axios.get(`${BASE_URL}/health`, { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + }); + console.log(response.data); + } catch (error) { + console.error('Error:', error); + } + } + + checkHealth(); + ``` + +### Basic Agent + +=== "Python" + + ```python linenums="1" title="single_agent.py" + import os + import requests + from dotenv import load_dotenv + + load_dotenv() + + API_KEY = os.getenv("SWARMS_API_KEY") # (1) + BASE_URL = "https://api.swarms.world" + + headers = { + "x-api-key": API_KEY, + "Content-Type": "application/json" + } + + def run_single_agent(): + """Run a single agent with the AgentCompletion format""" + payload = { + "agent_config": { + "agent_name": "Research Analyst", # (2) + "description": "An expert in analyzing and synthesizing research data", + "system_prompt": ( # (3) + "You are a Research Analyst with expertise in data analysis and synthesis. " + "Your role is to analyze provided information, identify key insights, " + "and present findings in a clear, structured format." + ), + "model_name": "claude-3-5-sonnet-20240620", # (4) + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 1, + "auto_generate_prompt": False, + "tools_list_dictionary": None, + }, + "task": "What are the key trends in renewable energy adoption?", # (5) + } + + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() + + # Run the agent + result = run_single_agent() + print(result) + ``` + + 1. Load API key from environment variables + 2. Give your agent a descriptive name + 3. Define the agent's capabilities and role + 4. Choose from available models + 5. Specify the task for the agent + +=== "cURL" + + ```bash title="single_agent.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Research Analyst", + "description": "An expert in analyzing and synthesizing research data", + "system_prompt": "You are a Research Analyst with expertise in data analysis and synthesis. Your role is to analyze provided information, identify key insights, and present findings in a clear, structured format.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 1, + "auto_generate_prompt": false, + "tools_list_dictionary": null + }, + "task": "What are the key trends in renewable energy adoption?" + }' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="single_agent.ts" + import axios from 'axios'; + import * as dotenv from 'dotenv'; + + dotenv.config(); + + const API_KEY = process.env.SWARMS_API_KEY; + const BASE_URL = 'https://api.swarms.world'; + + interface AgentConfig { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; + max_tokens: number; + temperature: number; + auto_generate_prompt: boolean; + tools_list_dictionary: null | object[]; + } + + interface AgentPayload { + agent_config: AgentConfig; + task: string; + } + + async function runSingleAgent() { + const payload: AgentPayload = { + agent_config: { + agent_name: "Research Analyst", + description: "An expert in analyzing and synthesizing research data", + system_prompt: "You are a Research Analyst with expertise in data analysis and synthesis.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 1, + auto_generate_prompt: false, + tools_list_dictionary: null + }, + task: "What are the key trends in renewable energy adoption?" + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + + // Run the agent + runSingleAgent() + .then(result => console.log(result)) + .catch(error => console.error(error)); + ``` + +### Agent with History + +=== "Python" + + ```python linenums="1" title="agent_with_history.py" + def run_agent_with_history(): + payload = { + "agent_config": { + "agent_name": "Conversation Agent", + "description": "An agent that maintains conversation context", + "system_prompt": "You are a helpful assistant that maintains context.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": False, + }, + "task": "What's the weather like?", + "history": [ # (1) + { + "role": "user", + "content": "I'm planning a trip to New York." + }, + { + "role": "assistant", + "content": "That's great! When are you planning to visit?" + }, + { + "role": "user", + "content": "Next week." + } + ] + } + + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() + ``` + + 1. Include conversation history for context + +=== "cURL" + + ```bash title="agent_with_history.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Conversation Agent", + "description": "An agent that maintains conversation context", + "system_prompt": "You are a helpful assistant that maintains context.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": false + }, + "task": "What'\''s the weather like?", + "history": [ + { + "role": "user", + "content": "I'\''m planning a trip to New York." + }, + { + "role": "assistant", + "content": "That'\''s great! When are you planning to visit?" + }, + { + "role": "user", + "content": "Next week." + } + ] + }' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="agent_with_history.ts" + interface Message { + role: 'user' | 'assistant'; + content: string; + } + + interface AgentWithHistoryPayload extends AgentPayload { + history: Message[]; + } + + async function runAgentWithHistory() { + const payload: AgentWithHistoryPayload = { + agent_config: { + agent_name: "Conversation Agent", + description: "An agent that maintains conversation context", + system_prompt: "You are a helpful assistant that maintains context.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false, + tools_list_dictionary: null + }, + task: "What's the weather like?", + history: [ + { + role: "user", + content: "I'm planning a trip to New York." + }, + { + role: "assistant", + content: "That's great! When are you planning to visit?" + }, + { + role: "user", + content: "Next week." + } + ] + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` + +## Multi-Agent Swarms + +!!! tip "Swarm Types" + + Swarms API supports two types of agent workflows: + + 1. `SequentialWorkflow`: Agents work in sequence, each building on previous output + 2. `ConcurrentWorkflow`: Agents work in parallel on the same task + +### Sequential Workflow + +=== "Python" + + ```python linenums="1" title="sequential_swarm.py" + def run_sequential_swarm(): + payload = { + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", # (1) + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + }, + { + "agent_name": "Economic Forecaster", # (2) + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", # (3) + "task": "Analyze the current market conditions and provide economic forecasts." + } + + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload + ) + return response.json() + ``` + + 1. First agent analyzes market trends + 2. Second agent builds on first agent's analysis + 3. Sequential workflow ensures ordered execution + +=== "cURL" + + ```bash title="sequential_swarm.sh" + curl -X POST "https://api.swarms.world/v1/swarm/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Financial Analysis Swarm", + "description": "Market analysis swarm", + "agents": [ + { + "agent_name": "Market Analyst", + "description": "Analyzes market trends", + "system_prompt": "You are a financial analyst expert.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + }, + { + "agent_name": "Economic Forecaster", + "description": "Predicts economic trends", + "system_prompt": "You are an expert in economic forecasting.", + "model_name": "gpt-4o", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Analyze the current market conditions and provide economic forecasts." + }' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="sequential_swarm.ts" + interface SwarmAgent { + agent_name: string; + description: string; + system_prompt: string; + model_name: string; + role: string; + max_loops: number; + max_tokens: number; + temperature: number; + auto_generate_prompt: boolean; + } + + interface SwarmPayload { + name: string; + description: string; + agents: SwarmAgent[]; + max_loops: number; + swarm_type: 'SequentialWorkflow' | 'ConcurrentWorkflow'; + task: string; + } + + async function runSequentialSwarm() { + const payload: SwarmPayload = { + name: "Financial Analysis Swarm", + description: "Market analysis swarm", + agents: [ + { + agent_name: "Market Analyst", + description: "Analyzes market trends", + system_prompt: "You are a financial analyst expert.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + }, + { + agent_name: "Economic Forecaster", + description: "Predicts economic trends", + system_prompt: "You are an expert in economic forecasting.", + model_name: "gpt-4o", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Analyze the current market conditions and provide economic forecasts." + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` + +### Concurrent Workflow + +=== "Python" + + ```python linenums="1" title="concurrent_swarm.py" + def run_concurrent_swarm(): + payload = { + "name": "Medical Analysis Swarm", + "description": "Analyzes medical data concurrently", + "agents": [ + { + "agent_name": "Lab Data Analyzer", # (1) + "description": "Analyzes lab report data", + "system_prompt": "You are a medical data analyst specializing in lab results.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + }, + { + "agent_name": "Clinical Specialist", # (2) + "description": "Provides clinical interpretations", + "system_prompt": "You are an expert in clinical diagnosis.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": False + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", # (3) + "task": "Analyze these lab results and provide clinical interpretations." + } + + response = requests.post( + f"{BASE_URL}/v1/swarm/completions", + headers=headers, + json=payload + ) + return response.json() + ``` + + 1. First agent processes lab data + 2. Second agent works simultaneously + 3. Concurrent workflow for parallel processing + +=== "cURL" + + ```bash title="concurrent_swarm.sh" + curl -X POST "https://api.swarms.world/v1/swarm/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Medical Analysis Swarm", + "description": "Analyzes medical data concurrently", + "agents": [ + { + "agent_name": "Lab Data Analyzer", + "description": "Analyzes lab report data", + "system_prompt": "You are a medical data analyst specializing in lab results.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + }, + { + "agent_name": "Clinical Specialist", + "description": "Provides clinical interpretations", + "system_prompt": "You are an expert in clinical diagnosis.", + "model_name": "claude-3-5-sonnet-20240620", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.5, + "auto_generate_prompt": false + } + ], + "max_loops": 1, + "swarm_type": "ConcurrentWorkflow", + "task": "Analyze these lab results and provide clinical interpretations." + }' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="concurrent_swarm.ts" + async function runConcurrentSwarm() { + const payload: SwarmPayload = { + name: "Medical Analysis Swarm", + description: "Analyzes medical data concurrently", + agents: [ + { + agent_name: "Lab Data Analyzer", + description: "Analyzes lab report data", + system_prompt: "You are a medical data analyst specializing in lab results.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + }, + { + agent_name: "Clinical Specialist", + description: "Provides clinical interpretations", + system_prompt: "You are an expert in clinical diagnosis.", + model_name: "claude-3-5-sonnet-20240620", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.5, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "ConcurrentWorkflow", + task: "Analyze these lab results and provide clinical interpretations." + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` + +### Batch Processing + +!!! example "Batch Processing" + + Process multiple swarms in a single request for improved efficiency. + +=== "Python" + + ```python linenums="1" title="batch_swarms.py" + def run_batch_swarms(): + payload = [ + { + "name": "Batch Swarm 1", + "description": "First swarm in batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." + } + ] + + response = requests.post( + f"{BASE_URL}/v1/swarm/batch/completions", + headers=headers, + json=payload + ) + return response.json() + ``` + +=== "cURL" + + ```bash title="batch_swarms.sh" + curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "name": "Batch Swarm 1", + "description": "First swarm in batch", + "agents": [ + { + "agent_name": "Research Agent", + "description": "Conducts research", + "system_prompt": "You are a research assistant.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + }, + { + "agent_name": "Analysis Agent", + "description": "Analyzes data", + "system_prompt": "You are a data analyst.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1 + } + ], + "max_loops": 1, + "swarm_type": "SequentialWorkflow", + "task": "Research AI advancements." + } + ]' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="batch_swarms.ts" + async function runBatchSwarms() { + const payload: SwarmPayload[] = [ + { + name: "Batch Swarm 1", + description: "First swarm in batch", + agents: [ + { + agent_name: "Research Agent", + description: "Conducts research", + system_prompt: "You are a research assistant.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false + }, + { + agent_name: "Analysis Agent", + description: "Analyzes data", + system_prompt: "You are a data analyst.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false + } + ], + max_loops: 1, + swarm_type: "SequentialWorkflow", + task: "Research AI advancements." + } + ]; + + try { + const response = await axios.post( + `${BASE_URL}/v1/swarm/batch/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` + +## Advanced Features + +### Tools Integration + +!!! note "Tools" + + Enhance agent capabilities by providing them with specialized tools. + +=== "Python" + + ```python linenums="1" title="tools_example.py" + def run_agent_with_tools(): + tools_dictionary = [ + { + "type": "function", + "function": { + "name": "search_topic", + "description": "Conduct an in-depth search on a topic", + "parameters": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Search depth (1-3)" + }, + "detailed_queries": { + "type": "array", + "description": "Specific search queries", + "items": { + "type": "string" + } + } + }, + "required": ["depth", "detailed_queries"] + } + } + } + ] + + payload = { + "agent_config": { + "agent_name": "Research Assistant", + "description": "Expert in research with search capabilities", + "system_prompt": "You are a research assistant with search capabilities.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": False, + "tools_dictionary": tools_dictionary + }, + "task": "Research the latest developments in quantum computing." + } + + response = requests.post( + f"{BASE_URL}/v1/agent/completions", + headers=headers, + json=payload + ) + return response.json() + ``` + +=== "cURL" + + ```bash title="tools_example.sh" + curl -X POST "https://api.swarms.world/v1/agent/completions" \ + -H "x-api-key: $SWARMS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "agent_config": { + "agent_name": "Research Assistant", + "description": "Expert in research with search capabilities", + "system_prompt": "You are a research assistant with search capabilities.", + "model_name": "gpt-4", + "role": "worker", + "max_loops": 1, + "max_tokens": 8192, + "temperature": 0.7, + "auto_generate_prompt": false, + "tools_dictionary": [ + { + "type": "function", + "function": { + "name": "search_topic", + "description": "Conduct an in-depth search on a topic", + "parameters": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Search depth (1-3)" + }, + "detailed_queries": { + "type": "array", + "description": "Specific search queries", + "items": { + "type": "string" + } + } + }, + "required": ["depth", "detailed_queries"] + } + } + } + ] + }, + "task": "Research the latest developments in quantum computing." + }' + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="tools_example.ts" + interface ToolFunction { + name: string; + description: string; + parameters: { + type: string; + properties: { + [key: string]: { + type: string; + description: string; + items?: { + type: string; + }; + }; + }; + required: string[]; + }; + } + + interface Tool { + type: string; + function: ToolFunction; + } + + interface AgentWithToolsConfig extends AgentConfig { + tools_dictionary: Tool[]; + } + + interface AgentWithToolsPayload { + agent_config: AgentWithToolsConfig; + task: string; + } + + async function runAgentWithTools() { + const toolsDictionary: Tool[] = [ + { + type: "function", + function: { + name: "search_topic", + description: "Conduct an in-depth search on a topic", + parameters: { + type: "object", + properties: { + depth: { + type: "integer", + description: "Search depth (1-3)" + }, + detailed_queries: { + type: "array", + description: "Specific search queries", + items: { + type: "string" + } + } + }, + required: ["depth", "detailed_queries"] + } + } + } + ]; + + const payload: AgentWithToolsPayload = { + agent_config: { + agent_name: "Research Assistant", + description: "Expert in research with search capabilities", + system_prompt: "You are a research assistant with search capabilities.", + model_name: "gpt-4", + role: "worker", + max_loops: 1, + max_tokens: 8192, + temperature: 0.7, + auto_generate_prompt: false, + tools_dictionary: toolsDictionary + }, + task: "Research the latest developments in quantum computing." + }; + + try { + const response = await axios.post( + `${BASE_URL}/v1/agent/completions`, + payload, + { + headers: { + 'x-api-key': API_KEY, + 'Content-Type': 'application/json' + } + } + ); + return response.data; + } catch (error) { + console.error('Error:', error); + throw error; + } + } + ``` + +### Available Models + +!!! info "Supported Models" + + Choose the right model for your use case: + + === "OpenAI" + - `gpt-4` + - `gpt-4o` + - `gpt-4o-mini` + + === "Anthropic" + - `claude-3-5-sonnet-20240620` + - `claude-3-7-sonnet-latest` + + === "Groq" + - `groq/llama3-70b-8192` + - `groq/deepseek-r1-distill-llama-70b` + +## Best Practices + +!!! danger "Security" + Never commit API keys or sensitive credentials to version control. + +!!! warning "Rate Limits" + Implement proper rate limiting and error handling in production. + +!!! tip "Testing" + Start with simple tasks and gradually increase complexity. + +=== "Python" + + ```python linenums="1" title="best_practices.py" + # Error Handling + try: + response = requests.post(url, headers=headers, json=payload) + response.raise_for_status() + except requests.exceptions.RequestException as e: + print(f"Error: {e}") + + # Rate Limiting + import time + from tenacity import retry, wait_exponential + + @retry(wait=wait_exponential(multiplier=1, min=4, max=10)) + def make_api_call(): + response = requests.post(url, headers=headers, json=payload) + response.raise_for_status() + return response + + # Input Validation + def validate_payload(payload): + required_fields = ["agent_config", "task"] + if not all(field in payload for field in required_fields): + raise ValueError("Missing required fields") + ``` + +=== "TypeScript" + + ```typescript linenums="1" title="best_practices.ts" + // Error Handling + try { + const response = await axios.post(url, payload, { headers }); + } catch (error) { + if (axios.isAxiosError(error)) { + console.error('API Error:', error.response?.data); + } + throw error; + } + + // Rate Limiting + import { rateLimit } from 'axios-rate-limit'; + + const http = rateLimit(axios.create(), { + maxRequests: 2, + perMilliseconds: 1000 + }); + + // Input Validation + function validatePayload(payload: unknown): asserts payload is AgentPayload { + if (!payload || typeof payload !== 'object') { + throw new Error('Invalid payload'); + } + + const { agent_config, task } = payload as Partial; + + if (!agent_config || !task) { + throw new Error('Missing required fields'); + } + } + ``` + +## Connect With Us + +Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights! + +| Platform | Description | Link | +|----------|-------------|------| +| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) | +| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) | +| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/jM3Z6M9uMq) | +| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) | +| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | +| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | +| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) | +| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) | \ No newline at end of file diff --git a/docs/swarms_cloud/rate_limits.md b/docs/swarms_cloud/rate_limits.md new file mode 100644 index 00000000..d0fb9759 --- /dev/null +++ b/docs/swarms_cloud/rate_limits.md @@ -0,0 +1,59 @@ +# Swarms API Rate Limits + +The Swarms API implements rate limiting to ensure fair usage and system stability. Here are the current limits: + +## Standard Rate Limits + +- **General API Requests**: 100 requests per minute +- **Batch Operations**: Maximum 10 requests per batch for agent/swarm batch operations + +## Rate Limit Response + +When you exceed the rate limit, the API will return a 429 (Too Many Requests) status code with the following message: +```json +{ + "detail": "Rate limit exceeded. Please try again later." +} +``` + +## Batch Operation Limits + +For batch operations (`/v1/agent/batch/completions` and `/v1/swarm/batch/completions`): + +- Maximum 10 concurrent requests per batch + +- Exceeding this limit will result in a 400 (Bad Request) error + +## Increasing Your Rate Limits + +Need higher rate limits for your application? You can increase your limits by subscribing to a higher tier plan at [swarms.world/pricing](https://swarms.world/pricing). + +Higher tier plans offer: + +- Increased rate limits + +- Higher batch operation limits + +- Priority processing + +- Dedicated support + +## Best Practices + +To make the most of your rate limits: + +1. Implement proper error handling for rate limit responses + +2. Use batch operations when processing multiple requests + +3. Add appropriate retry logic with exponential backoff + +4. Monitor your API usage to stay within limits + +## Rate Limit Headers + +The API does not currently expose rate limit headers. We recommend implementing your own request tracking to stay within the limits. + +--- + +For questions about rate limits or to request a custom plan for higher limits, please contact our support team or visit [swarms.world/pricing](https://swarms.world/pricing). \ No newline at end of file diff --git a/docs/swarms_cloud/swarm_types.md b/docs/swarms_cloud/swarm_types.md index 795f9ad5..f6091501 100644 --- a/docs/swarms_cloud/swarm_types.md +++ b/docs/swarms_cloud/swarm_types.md @@ -1,54 +1,30 @@ -### Available Swarms in The Swarms API +# Multi-Agent Architectures -| Swarm Type | Description (English) | Description (Chinese) | -|----------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------| -| AgentRearrange | A swarm type focused on rearranging agents for optimal performance. | 一种专注于重新排列代理以实现最佳性能的群类型。 | -| MixtureOfAgents | Combines different types of agents to achieve a specific goal. | 结合不同类型的代理以实现特定目标。 | -| SpreadSheetSwarm | Utilizes spreadsheet-like structures for data management and operations. | 利用类似电子表格的结构进行数据管理和操作。 | -| SequentialWorkflow | Executes tasks in a sequential manner. | 以顺序方式执行任务。 | -| ConcurrentWorkflow | Allows tasks to be executed concurrently for efficiency. | 允许任务并发执行以提高效率。 | -| GroupChat | Facilitates communication among agents in a group chat format. | 以群聊格式促进代理之间的沟通。 | -| MultiAgentRouter | Routes tasks and information among multiple agents. | 在多个代理之间路由任务和信息。 | -| AutoSwarmBuilder | Automatically builds and configures swarms based on predefined criteria. | 根据预定义标准自动构建和配置群。 | -| HiearchicalSwarm | Organizes agents in a hierarchical structure for task delegation. | 以层次结构组织代理以进行任务委派。 | -| auto | Automatically selects the best swarm type based on the context. | 根据上下文自动选择最佳群类型。 | -| MajorityVoting | Uses majority voting among agents to make decisions. | 使用代理之间的多数投票来做出决策。 | -| MALT | A specialized swarm type for specific tasks (details needed). | 一种专门为特定任务设计的群类型（需要详细信息）。 | +Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Here's a comprehensive overview of each available swarm: -### Documentation for Swarms +| Swarm Type | Description | Learn More | +|---------------------|------------------------------------------------------------------------------|------------| +| AgentRearrange | Dynamically reorganizes agents to optimize task performance and efficiency. Optimizes agent performance by dynamically adjusting their roles and positions within the workflow. This architecture is particularly useful when the effectiveness of agents depends on their sequence or arrangement. | [Learn More](/swarms/structs/agent_rearrange) | +| MixtureOfAgents | Creates diverse teams of specialized agents, each bringing unique capabilities to solve complex problems. Each agent contributes unique skills to achieve the overall goal, making it excel at tasks requiring multiple types of expertise or processing. | [Learn More](/swarms/structs/moa) | +| SpreadSheetSwarm | Provides a structured approach to data management and operations, making it ideal for tasks involving data analysis, transformation, and systematic processing in a spreadsheet-like structure. | [Learn More](/swarms/structs/spreadsheet_swarm) | +| SequentialWorkflow | Ensures strict process control by executing tasks in a predefined order. Perfect for workflows where each step depends on the completion of previous steps. | [Learn More](/swarms/structs/sequential_workflow) | +| ConcurrentWorkflow | Maximizes efficiency by running independent tasks in parallel, significantly reducing overall processing time for complex operations. Ideal for independent tasks that can be processed simultaneously. | [Learn More](/swarms/structs/concurrentworkflow) | +| GroupChat | Enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. | [Learn More](/swarms/structs/group_chat) | +| MultiAgentRouter | Acts as an intelligent task dispatcher, ensuring optimal distribution of work across available agents based on their capabilities and current workload. | [Learn More](/swarms/structs/multi_agent_router) | +| AutoSwarmBuilder | Simplifies swarm creation by automatically configuring agent architectures based on task requirements and performance metrics. | [Learn More](/swarms/structs/auto_swarm_builder) | +| HiearchicalSwarm | Implements a structured approach to task management, with clear lines of authority and delegation across multiple agent levels. | [Learn More](/swarms/structs/multi_swarm_orchestration) | +| auto | Provides intelligent swarm selection based on context, automatically choosing the most effective architecture for given tasks. | [Learn More](/swarms/concept/how_to_choose_swarms) | +| MajorityVoting | Implements robust decision-making through consensus, particularly useful for tasks requiring collective intelligence or verification. | [Learn More](/swarms/structs/majorityvoting) | +| MALT | Specialized framework for language-based tasks, optimizing agent collaboration for complex language processing operations. | [Learn More](/swarms/structs/malt) | -1. **AgentRearrange**: This swarm type is designed to rearrange agents to optimize their performance in a given task. It is useful in scenarios where agent positioning or order affects the outcome. - - 这种群类型旨在重新排列代理以优化其在给定任务中的性能。它在代理位置或顺序影响结果的情况下非常有用。 +# Learn More -2. **MixtureOfAgents**: This type combines various agents, each with unique capabilities, to work together towards a common goal. It leverages the strengths of different agents to enhance overall performance. - - 这种类型结合了各种代理，每个代理都有独特的能力，共同努力实现共同目标。它利用不同代理的优势来提高整体性能。 +To learn more about Swarms architecture and how different swarm types work together, visit our comprehensive guides: -3. **SpreadSheetSwarm**: This swarm type uses spreadsheet-like structures to manage and operate on data. It is ideal for tasks that require organized data manipulation and analysis. - - 这种群类型使用类似电子表格的结构来管理和操作数据。它非常适合需要有组织的数据操作和分析的任务。 +- [Introduction to Multi-Agent Architectures](/swarms/concept/swarm_architectures) -4. **SequentialWorkflow**: Tasks are executed one after another in this swarm type, ensuring that each step is completed before the next begins. It is suitable for processes that require strict order. - - 在这种群类型中，任务一个接一个地执行，确保每个步骤在下一个步骤开始之前完成。它适用于需要严格顺序的流程。 +- [How to Choose the Right Multi-Agent Architecture](/swarms/concept/how_to_choose_swarms) -5. **ConcurrentWorkflow**: This type allows multiple tasks to be executed simultaneously, improving efficiency and reducing time for completion. It is best for independent tasks that do not rely on each other. - - 这种类型允许多个任务同时执行，提高效率并减少完成时间。它最适合不相互依赖的独立任务。 +- [Framework Architecture Overview](/swarms/concept/framework_architecture) -6. **GroupChat**: Facilitates communication among agents in a group chat format, enabling real-time collaboration and decision-making. - - 以群聊格式促进代理之间的沟通，实现实时协作和决策。 - -7. **MultiAgentRouter**: This swarm type routes tasks and information among multiple agents, ensuring that each agent receives the necessary data to perform its function. - - 这种群类型在多个代理之间路由任务和信息，确保每个代理接收到执行其功能所需的数据。 - -8. **AutoSwarmBuilder**: Automatically builds and configures swarms based on predefined criteria, reducing the need for manual setup and configuration. - - 根据预定义标准自动构建和配置群，减少手动设置和配置的需要。 - -9. **HiearchicalSwarm**: Organizes agents in a hierarchical structure, allowing for efficient task delegation and management. - - 以层次结构组织代理，允许高效的任务委派和管理。 - -10. **auto**: Automatically selects the most appropriate swarm type based on the context and requirements of the task. - - 根据任务的上下文和要求自动选择最合适的群类型。 - -11. **MajorityVoting**: Uses a majority voting mechanism among agents to make decisions, ensuring that the most popular choice is selected. - - 使用代理之间的多数投票机制来做出决策，确保选择最受欢迎的选项。 - -12. **MALT**: A specialized swarm type designed for specific tasks. Further details are needed to fully document this type. - - 一种专门为特定任务设计的群类型。需要进一步的详细信息来完整记录这种类型。 +- [Building Custom Swarms](/swarms/structs/custom_swarm) diff --git a/examples/multi_agent/interactive_groupchat_examples/interactive_groupchat_speaker_example.py b/examples/multi_agent/interactive_groupchat_examples/interactive_groupchat_speaker_example.py new file mode 100644 index 00000000..e2d1b9fc --- /dev/null +++ b/examples/multi_agent/interactive_groupchat_examples/interactive_groupchat_speaker_example.py @@ -0,0 +1,163 @@ +""" +Medical Panel Discussion Example + +This example demonstrates a panel of medical specialists discussing treatment solutions +for various diseases using InteractiveGroupChat with different speaker functions: +- Round Robin: Doctors speak in a fixed order +- Random: Doctors speak in random order +- Priority: Senior doctors speak first +- Custom: Disease-specific speaker function + +The panel includes specialists from different medical fields who can collaborate +on complex medical cases and treatment plans. +""" + +from swarms import Agent +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, +) + + +def create_medical_panel(): + """Create a panel of medical specialists for discussion.""" + + # Cardiologist - Heart and cardiovascular system specialist + cardiologist = Agent( + agent_name="cardiologist", + system_prompt="""You are Dr. Sarah Chen, a board-certified cardiologist with 15 years of experience. + You specialize in cardiovascular diseases, heart failure, arrhythmias, and interventional cardiology. + You have expertise in: + - Coronary artery disease and heart attacks + - Heart failure and cardiomyopathy + - Arrhythmias and electrophysiology + - Hypertension and lipid disorders + - Cardiac imaging and diagnostic procedures + + When discussing cases, provide evidence-based treatment recommendations, + consider patient risk factors, and collaborate with other specialists for comprehensive care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Oncologist - Cancer specialist + oncologist = Agent( + agent_name="oncologist", + system_prompt="""You are Dr. Michael Rodriguez, a medical oncologist with 12 years of experience. + You specialize in the diagnosis and treatment of various types of cancer. + You have expertise in: + - Solid tumors (lung, breast, colon, prostate, etc.) + - Hematologic malignancies (leukemia, lymphoma, multiple myeloma) + - Targeted therapy and immunotherapy + - Clinical trials and novel treatments + - Palliative care and symptom management + + When discussing cases, consider the cancer type, stage, molecular profile, + patient performance status, and available treatment options including clinical trials.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Neurologist - Nervous system specialist + neurologist = Agent( + agent_name="neurologist", + system_prompt="""You are Dr. Emily Watson, a neurologist with 10 years of experience. + You specialize in disorders of the nervous system, brain, and spinal cord. + You have expertise in: + - Stroke and cerebrovascular disease + - Neurodegenerative disorders (Alzheimer's, Parkinson's, ALS) + - Multiple sclerosis and demyelinating diseases + - Epilepsy and seizure disorders + - Headache and migraine disorders + - Neuromuscular diseases + + When discussing cases, consider neurological symptoms, imaging findings, + and the impact of neurological conditions on overall patient care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Endocrinologist - Hormone and metabolism specialist + endocrinologist = Agent( + agent_name="endocrinologist", + system_prompt="""You are Dr. James Thompson, an endocrinologist with 8 years of experience. + You specialize in disorders of the endocrine system and metabolism. + You have expertise in: + - Diabetes mellitus (Type 1, Type 2, gestational) + - Thyroid disorders (hyperthyroidism, hypothyroidism, thyroid cancer) + - Adrenal disorders and Cushing's syndrome + - Pituitary disorders and growth hormone issues + - Osteoporosis and calcium metabolism + - Reproductive endocrinology + + When discussing cases, consider metabolic factors, hormone levels, + and how endocrine disorders may affect other organ systems.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Infectious Disease Specialist + infectious_disease = Agent( + agent_name="infectious_disease", + system_prompt="""You are Dr. Lisa Park, an infectious disease specialist with 11 years of experience. + You specialize in the diagnosis and treatment of infectious diseases. + You have expertise in: + - Bacterial, viral, fungal, and parasitic infections + - Antibiotic resistance and antimicrobial stewardship + - HIV/AIDS and opportunistic infections + - Travel medicine and tropical diseases + - Hospital-acquired infections + - Emerging infectious diseases + + When discussing cases, consider the infectious agent, antimicrobial susceptibility, + host factors, and infection control measures.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + return [ + cardiologist, + oncologist, + neurologist, + endocrinologist, + infectious_disease, + ] + + +def example_round_robin_panel(): + """Example with round robin speaking order.""" + print("=== ROUND ROBIN MEDICAL PANEL ===\n") + + agents = create_medical_panel() + + group_chat = InteractiveGroupChat( + name="Medical Panel Discussion", + description="A collaborative panel of medical specialists discussing complex cases", + agents=agents, + speaker_function="round-robin-speaker", + interactive=False, + ) + + print(group_chat.speaker_function) + + # Case 1: Complex patient with multiple conditions + case1 = """CASE PRESENTATION: + A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of + stage 3 colon cancer presents with chest pain and shortness of breath. + ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) + and signs of infection (WBC 15,000, CRP elevated). + + @cardiologist @oncologist @endocrinologist @infectious_disease please provide your + assessment and treatment recommendations for this complex case.""" + + response = group_chat.run(case1) + print(f"Response:\n{response}\n") + print("=" * 80 + "\n") + + +if __name__ == "__main__": + example_round_robin_panel() diff --git a/examples/multi_agent/interactive_groupchat_examples/medical_panel_example.py b/examples/multi_agent/interactive_groupchat_examples/medical_panel_example.py new file mode 100644 index 00000000..0e31c96e --- /dev/null +++ b/examples/multi_agent/interactive_groupchat_examples/medical_panel_example.py @@ -0,0 +1,162 @@ +""" +Medical Panel Discussion Example + +This example demonstrates a panel of medical specialists discussing treatment solutions +for various diseases using InteractiveGroupChat with different speaker functions: +- Round Robin: Doctors speak in a fixed order +- Random: Doctors speak in random order +- Priority: Senior doctors speak first +- Custom: Disease-specific speaker function + +The panel includes specialists from different medical fields who can collaborate +on complex medical cases and treatment plans. +""" + +from swarms import Agent +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, + round_robin_speaker, +) + + +def create_medical_panel(): + """Create a panel of medical specialists for discussion.""" + + # Cardiologist - Heart and cardiovascular system specialist + cardiologist = Agent( + agent_name="cardiologist", + system_prompt="""You are Dr. Sarah Chen, a board-certified cardiologist with 15 years of experience. + You specialize in cardiovascular diseases, heart failure, arrhythmias, and interventional cardiology. + You have expertise in: + - Coronary artery disease and heart attacks + - Heart failure and cardiomyopathy + - Arrhythmias and electrophysiology + - Hypertension and lipid disorders + - Cardiac imaging and diagnostic procedures + + When discussing cases, provide evidence-based treatment recommendations, + consider patient risk factors, and collaborate with other specialists for comprehensive care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Oncologist - Cancer specialist + oncologist = Agent( + agent_name="oncologist", + system_prompt="""You are Dr. Michael Rodriguez, a medical oncologist with 12 years of experience. + You specialize in the diagnosis and treatment of various types of cancer. + You have expertise in: + - Solid tumors (lung, breast, colon, prostate, etc.) + - Hematologic malignancies (leukemia, lymphoma, multiple myeloma) + - Targeted therapy and immunotherapy + - Clinical trials and novel treatments + - Palliative care and symptom management + + When discussing cases, consider the cancer type, stage, molecular profile, + patient performance status, and available treatment options including clinical trials.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Neurologist - Nervous system specialist + neurologist = Agent( + agent_name="neurologist", + system_prompt="""You are Dr. Emily Watson, a neurologist with 10 years of experience. + You specialize in disorders of the nervous system, brain, and spinal cord. + You have expertise in: + - Stroke and cerebrovascular disease + - Neurodegenerative disorders (Alzheimer's, Parkinson's, ALS) + - Multiple sclerosis and demyelinating diseases + - Epilepsy and seizure disorders + - Headache and migraine disorders + - Neuromuscular diseases + + When discussing cases, consider neurological symptoms, imaging findings, + and the impact of neurological conditions on overall patient care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Endocrinologist - Hormone and metabolism specialist + endocrinologist = Agent( + agent_name="endocrinologist", + system_prompt="""You are Dr. James Thompson, an endocrinologist with 8 years of experience. + You specialize in disorders of the endocrine system and metabolism. + You have expertise in: + - Diabetes mellitus (Type 1, Type 2, gestational) + - Thyroid disorders (hyperthyroidism, hypothyroidism, thyroid cancer) + - Adrenal disorders and Cushing's syndrome + - Pituitary disorders and growth hormone issues + - Osteoporosis and calcium metabolism + - Reproductive endocrinology + + When discussing cases, consider metabolic factors, hormone levels, + and how endocrine disorders may affect other organ systems.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Infectious Disease Specialist + infectious_disease = Agent( + agent_name="infectious_disease", + system_prompt="""You are Dr. Lisa Park, an infectious disease specialist with 11 years of experience. + You specialize in the diagnosis and treatment of infectious diseases. + You have expertise in: + - Bacterial, viral, fungal, and parasitic infections + - Antibiotic resistance and antimicrobial stewardship + - HIV/AIDS and opportunistic infections + - Travel medicine and tropical diseases + - Hospital-acquired infections + - Emerging infectious diseases + + When discussing cases, consider the infectious agent, antimicrobial susceptibility, + host factors, and infection control measures.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + return [ + cardiologist, + oncologist, + neurologist, + endocrinologist, + infectious_disease, + ] + + +def example_round_robin_panel(): + """Example with round robin speaking order.""" + print("=== ROUND ROBIN MEDICAL PANEL ===\n") + + agents = create_medical_panel() + + group_chat = InteractiveGroupChat( + name="Medical Panel Discussion", + description="A collaborative panel of medical specialists discussing complex cases", + agents=agents, + speaker_function=round_robin_speaker, + interactive=False, + ) + + # Case 1: Complex patient with multiple conditions + case1 = """CASE PRESENTATION: + A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of + stage 3 colon cancer presents with chest pain and shortness of breath. + ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) + and signs of infection (WBC 15,000, CRP elevated). + + @cardiologist @oncologist @endocrinologist @infectious_disease please provide your + assessment and treatment recommendations for this complex case.""" + + response = group_chat.run(case1) + print(f"Response:\n{response}\n") + print("=" * 80 + "\n") + + +if __name__ == "__main__": + example_round_robin_panel() diff --git a/speaker_function_examples.py b/examples/multi_agent/interactive_groupchat_examples/speaker_function_examples.py similarity index 86% rename from speaker_function_examples.py rename to examples/multi_agent/interactive_groupchat_examples/speaker_function_examples.py index f9255831..49a4ac40 100644 --- a/speaker_function_examples.py +++ b/examples/multi_agent/interactive_groupchat_examples/speaker_function_examples.py @@ -24,7 +24,7 @@ def create_example_agents(): analyst = Agent( agent_name="analyst", system_prompt="You are a data analyst. You excel at analyzing data, creating charts, and providing insights.", - model_name="gpt-4.1", + model_name="claude-3-5-sonnet-20240620", streaming_on=True, print_on=True, ) @@ -32,7 +32,7 @@ def create_example_agents(): researcher = Agent( agent_name="researcher", system_prompt="You are a research specialist. You are great at gathering information, fact-checking, and providing detailed research.", - model_name="gpt-4.1", + model_name="claude-3-5-sonnet-20240620", streaming_on=True, print_on=True, ) @@ -40,7 +40,7 @@ def create_example_agents(): writer = Agent( agent_name="writer", system_prompt="You are a content writer. You excel at writing clear, engaging content and summarizing information.", - model_name="gpt-4.1", + model_name="claude-3-5-sonnet-20240620", streaming_on=True, print_on=True, ) @@ -61,7 +61,7 @@ def example_random(): ) # Test the random behavior - task = "Let's create a marketing strategy. @analyst @researcher @writer please contribute." + task = "Let's create a marketing strategy for a personal healthcare ai consumer assistant app. @analyst @researcher @writer please contribute." response = group_chat.run(task) print(f"Response:\n{response}\n") diff --git a/stream_example.py b/examples/multi_agent/interactive_groupchat_examples/stream_example.py similarity index 73% rename from stream_example.py rename to examples/multi_agent/interactive_groupchat_examples/stream_example.py index 3234fb60..8517ff57 100644 --- a/stream_example.py +++ b/examples/multi_agent/interactive_groupchat_examples/stream_example.py @@ -3,10 +3,12 @@ from swarms import Agent # Enable real-time streaming agent = Agent( agent_name="StoryAgent", - model_name="gpt-4o-mini", + # model_name="groq/llama-3.1-8b-instant", + model_name="claude-3-5-sonnet-20240620", + # system_prompt="", streaming_on=True, # 🔥 This enables real streaming! max_loops=1, - print_on=False, + print_on=True, output_type="all", ) diff --git a/pyproject.toml b/pyproject.toml index 85cfd7ee..963c2c2c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api" [tool.poetry] name = "swarms" -version = "7.8.9" +version = "7.9.0" description = "Swarms - TGSC" license = "MIT" authors = ["Kye Gomez "] diff --git a/random_dynamic_speaker_example.py b/random_dynamic_speaker_example.py new file mode 100644 index 00000000..56c62049 --- /dev/null +++ b/random_dynamic_speaker_example.py @@ -0,0 +1,162 @@ +""" +Medical Panel Discussion Example + +This example demonstrates a panel of medical specialists discussing treatment solutions +for various diseases using InteractiveGroupChat with different speaker functions: +- Round Robin: Doctors speak in a fixed order +- Random: Doctors speak in random order +- Priority: Senior doctors speak first +- Custom: Disease-specific speaker function + +The panel includes specialists from different medical fields who can collaborate +on complex medical cases and treatment plans. +""" + +from swarms import Agent +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, +) + + +def create_medical_panel(): + """Create a panel of medical specialists for discussion.""" + + # Cardiologist - Heart and cardiovascular system specialist + cardiologist = Agent( + agent_name="cardiologist", + system_prompt="""You are Dr. Sarah Chen, a board-certified cardiologist with 15 years of experience. + You specialize in cardiovascular diseases, heart failure, arrhythmias, and interventional cardiology. + You have expertise in: + - Coronary artery disease and heart attacks + - Heart failure and cardiomyopathy + - Arrhythmias and electrophysiology + - Hypertension and lipid disorders + - Cardiac imaging and diagnostic procedures + + When discussing cases, provide evidence-based treatment recommendations, + consider patient risk factors, and collaborate with other specialists for comprehensive care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Oncologist - Cancer specialist + oncologist = Agent( + agent_name="oncologist", + system_prompt="""You are Dr. Michael Rodriguez, a medical oncologist with 12 years of experience. + You specialize in the diagnosis and treatment of various types of cancer. + You have expertise in: + - Solid tumors (lung, breast, colon, prostate, etc.) + - Hematologic malignancies (leukemia, lymphoma, multiple myeloma) + - Targeted therapy and immunotherapy + - Clinical trials and novel treatments + - Palliative care and symptom management + + When discussing cases, consider the cancer type, stage, molecular profile, + patient performance status, and available treatment options including clinical trials.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Neurologist - Nervous system specialist + neurologist = Agent( + agent_name="neurologist", + system_prompt="""You are Dr. Emily Watson, a neurologist with 10 years of experience. + You specialize in disorders of the nervous system, brain, and spinal cord. + You have expertise in: + - Stroke and cerebrovascular disease + - Neurodegenerative disorders (Alzheimer's, Parkinson's, ALS) + - Multiple sclerosis and demyelinating diseases + - Epilepsy and seizure disorders + - Headache and migraine disorders + - Neuromuscular diseases + + When discussing cases, consider neurological symptoms, imaging findings, + and the impact of neurological conditions on overall patient care.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Endocrinologist - Hormone and metabolism specialist + endocrinologist = Agent( + agent_name="endocrinologist", + system_prompt="""You are Dr. James Thompson, an endocrinologist with 8 years of experience. + You specialize in disorders of the endocrine system and metabolism. + You have expertise in: + - Diabetes mellitus (Type 1, Type 2, gestational) + - Thyroid disorders (hyperthyroidism, hypothyroidism, thyroid cancer) + - Adrenal disorders and Cushing's syndrome + - Pituitary disorders and growth hormone issues + - Osteoporosis and calcium metabolism + - Reproductive endocrinology + + When discussing cases, consider metabolic factors, hormone levels, + and how endocrine disorders may affect other organ systems.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + # Infectious Disease Specialist + infectious_disease = Agent( + agent_name="infectious_disease", + system_prompt="""You are Dr. Lisa Park, an infectious disease specialist with 11 years of experience. + You specialize in the diagnosis and treatment of infectious diseases. + You have expertise in: + - Bacterial, viral, fungal, and parasitic infections + - Antibiotic resistance and antimicrobial stewardship + - HIV/AIDS and opportunistic infections + - Travel medicine and tropical diseases + - Hospital-acquired infections + - Emerging infectious diseases + + When discussing cases, consider the infectious agent, antimicrobial susceptibility, + host factors, and infection control measures.""", + model_name="claude-3-5-sonnet-20240620", + streaming_on=True, + print_on=True, + ) + + return [ + cardiologist, + oncologist, + neurologist, + endocrinologist, + infectious_disease, + ] + + +def example_round_robin_panel(): + """Example with round robin speaking order.""" + print("=== ROUND ROBIN MEDICAL PANEL ===\n") + + agents = create_medical_panel() + + group_chat = InteractiveGroupChat( + name="Medical Panel Discussion", + description="A collaborative panel of medical specialists discussing complex cases", + agents=agents, + speaker_function="random-dynamic-speaker", + interactive=False, + ) + + print(group_chat.speaker_function) + print(group_chat.get_current_speaker_function()) + + # Case 1: Complex patient with multiple conditions + case1 = """CASE PRESENTATION: + A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of + stage 3 colon cancer presents with chest pain and shortness of breath. + ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) + and signs of infection (WBC 15,000, CRP elevated). + + @cardiologist @oncologist @endocrinologist @infectious_disease please provide your + assessment and treatment recommendations for this complex case.""" + + group_chat.run(case1) + + +if __name__ == "__main__": + example_round_robin_panel() diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index d47f6f67..bb005cc0 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -83,7 +83,14 @@ from swarms.structs.swarming_architectures import ( staircase_swarm, star_swarm, ) -from swarms.structs.interactive_groupchat import InteractiveGroupChat +from swarms.structs.interactive_groupchat import ( + InteractiveGroupChat, + speaker_function, + round_robin_speaker, + random_speaker, + priority_speaker, + random_dynamic_speaker, +) __all__ = [ "Agent", @@ -156,4 +163,9 @@ __all__ = [ "find_agent_by_name", "run_agent", "InteractiveGroupChat", + "speaker_function", + "round_robin_speaker", + "random_speaker", + "priority_speaker", + "random_dynamic_speaker", ] diff --git a/swarms/structs/agent.py b/swarms/structs/agent.py index d4039dfb..625e9784 100644 --- a/swarms/structs/agent.py +++ b/swarms/structs/agent.py @@ -1524,10 +1524,13 @@ class Agent: f"The model '{self.model_name}' does not support function calling. Please use a model that supports function calling." ) - if self.max_tokens > get_max_tokens(self.model_name): - raise AgentInitializationError( - f"Max tokens is set to {self.max_tokens}, but the model '{self.model_name}' only supports {get_max_tokens(self.model_name)} tokens. Please set max tokens to {get_max_tokens(self.model_name)} or less." - ) + try: + if self.max_tokens > get_max_tokens(self.model_name): + raise AgentInitializationError( + f"Max tokens is set to {self.max_tokens}, but the model '{self.model_name}' only supports {get_max_tokens(self.model_name)} tokens. Please set max tokens to {get_max_tokens(self.model_name)} or less." + ) + except Exception: + pass if self.model_name not in model_list: logger.warning( diff --git a/swarms/structs/interactive_groupchat.py b/swarms/structs/interactive_groupchat.py index 73e49b4b..9c0e8afe 100644 --- a/swarms/structs/interactive_groupchat.py +++ b/swarms/structs/interactive_groupchat.py @@ -121,6 +121,71 @@ def priority_speaker( return available_agents[-1] # Fallback +def random_dynamic_speaker( + agents: List[str], + response: str = "", + strategy: str = "parallel", + **kwargs, +) -> Union[str, List[str]]: + """ + Random dynamic speaker function that selects agents based on @mentions in responses. + + This function works in two phases: + 1. If no response is provided (first call), randomly selects an agent + 2. If a response is provided, extracts @mentions and returns agent(s) based on strategy + + Args: + agents: List of available agent names + response: The response from the previous agent (may contain @mentions) + strategy: How to handle multiple mentions - "sequential" or "parallel" + **kwargs: Additional arguments (ignored) + + Returns: + For sequential strategy: str (single agent name) + For parallel strategy: List[str] (list of agent names) + """ + if not agents: + raise ValueError( + "No agents provided for random dynamic selection" + ) + + # If no response provided, randomly select first agent + if not response: + return random.choice(agents) + + # Extract @mentions from the response + mentions = re.findall(r"@(\w+)", response) + + # Filter mentions to only include valid agents + valid_mentions = [ + mention for mention in mentions if mention in agents + ] + + if not valid_mentions: + # If no valid mentions, randomly select from all agents + return random.choice(agents) + + # Handle multiple mentions based on strategy + if strategy == "sequential": + # Return the first mentioned agent for sequential execution + return valid_mentions[0] + elif strategy == "parallel": + # Return all mentioned agents for parallel execution + return valid_mentions + else: + raise ValueError( + f"Invalid strategy: {strategy}. Must be 'sequential' or 'parallel'" + ) + + +speaker_functions = { + "round-robin-speaker": round_robin_speaker, + "random-speaker": random_speaker, + "priority-speaker": priority_speaker, + "random-dynamic-speaker": random_dynamic_speaker, +} + + class InteractiveGroupChat: """ An interactive group chat system that enables conversations with multiple agents using @mentions. @@ -145,11 +210,38 @@ class InteractiveGroupChat: max_loops (int, optional): Maximum conversation turns. Defaults to 1. output_type (str, optional): Type of output format. Defaults to "string". interactive (bool, optional): Whether to enable interactive terminal mode. Defaults to False. - speaker_function (Callable, optional): Function to determine speaking order. Defaults to round_robin_speaker. + speaker_function (Union[str, Callable], optional): Function to determine speaking order. Can be: + - A string name: "round-robin-speaker", "random-speaker", "priority-speaker", "random-dynamic-speaker" + - A custom callable function + - None (defaults to round_robin_speaker) speaker_state (dict, optional): Initial state for speaker function. Defaults to empty dict. Raises: ValueError: If invalid initialization parameters are provided + InvalidSpeakerFunctionError: If the speaker function is invalid + + Examples: + # Initialize with string-based speaker function + group_chat = InteractiveGroupChat( + agents=[agent1, agent2, agent3], + speaker_function="random-speaker" + ) + + # Initialize with priority speaker function + group_chat = InteractiveGroupChat( + agents=[agent1, agent2, agent3], + speaker_function="priority-speaker", + speaker_state={"priorities": {"agent1": 3, "agent2": 2, "agent3": 1}} + ) + + # Initialize with dynamic speaker function (agents mention each other) + group_chat = InteractiveGroupChat( + agents=[agent1, agent2, agent3], + speaker_function="random-dynamic-speaker" + ) + + # Change speaker function during runtime + group_chat.set_speaker_function("round-robin-speaker") """ def __init__( @@ -161,7 +253,7 @@ class InteractiveGroupChat: max_loops: int = 1, output_type: str = "string", interactive: bool = False, - speaker_function: Optional[Callable] = None, + speaker_function: Optional[Union[str, Callable]] = None, speaker_state: Optional[dict] = None, ): self.id = id @@ -173,9 +265,27 @@ class InteractiveGroupChat: self.interactive = interactive # Speaker function configuration - self.speaker_function = ( - speaker_function or round_robin_speaker - ) + if speaker_function is None: + self.speaker_function = round_robin_speaker + elif isinstance(speaker_function, str): + if speaker_function not in speaker_functions: + available_functions = ", ".join( + speaker_functions.keys() + ) + raise InvalidSpeakerFunctionError( + f"Invalid speaker function: '{speaker_function}'. " + f"Available functions: {available_functions}" + ) + self.speaker_function = speaker_functions[ + speaker_function + ] + elif callable(speaker_function): + self.speaker_function = speaker_function + else: + raise InvalidSpeakerFunctionError( + "Speaker function must be either a string, callable, or None" + ) + self.speaker_state = speaker_state or {"current_index": 0} # Validate speaker function @@ -197,6 +307,230 @@ class InteractiveGroupChat: self._setup_conversation_context() self._update_agent_prompts() + def set_speaker_function( + self, + speaker_function: Union[str, Callable], + speaker_state: Optional[dict] = None, + ) -> None: + """ + Set the speaker function using either a string name or a custom callable. + + Args: + speaker_function: Either a string name of a predefined function or a custom callable + String options: + - "round-robin-speaker": Cycles through agents in order + - "random-speaker": Selects agents randomly + - "priority-speaker": Selects based on priority weights + - "random-dynamic-speaker": Randomly selects first agent, then follows @mentions in responses + Callable: Custom function that takes (agents: List[str], **kwargs) -> str + speaker_state: Optional state for the speaker function + + Raises: + InvalidSpeakerFunctionError: If the speaker function is invalid + """ + if isinstance(speaker_function, str): + # Handle string-based speaker function + if speaker_function not in speaker_functions: + available_functions = ", ".join( + speaker_functions.keys() + ) + raise InvalidSpeakerFunctionError( + f"Invalid speaker function: '{speaker_function}'. " + f"Available functions: {available_functions}" + ) + self.speaker_function = speaker_functions[ + speaker_function + ] + logger.info( + f"Speaker function set to: {speaker_function}" + ) + elif callable(speaker_function): + # Handle callable speaker function + self.speaker_function = speaker_function + logger.info( + f"Custom speaker function set to: {speaker_function.__name__}" + ) + else: + raise InvalidSpeakerFunctionError( + "Speaker function must be either a string or a callable" + ) + + # Update speaker state if provided + if speaker_state: + self.speaker_state.update(speaker_state) + + # Validate the speaker function + self._validate_speaker_function() + + def set_priorities(self, priorities: dict) -> None: + """ + Set agent priorities for priority-based speaking order. + + Args: + priorities: Dictionary mapping agent names to priority weights + """ + self.speaker_state["priorities"] = priorities + logger.info(f"Agent priorities set: {priorities}") + + def get_available_speaker_functions(self) -> List[str]: + """ + Get a list of available speaker function names. + + Returns: + List[str]: List of available speaker function names + """ + return list(speaker_functions.keys()) + + def get_current_speaker_function(self) -> str: + """ + Get the name of the current speaker function. + + Returns: + str: Name of the current speaker function, or "custom" if it's a custom function + """ + for name, func in speaker_functions.items(): + if self.speaker_function == func: + return name + return "custom" + + def start_interactive_session(self): + """ + Start an interactive terminal session for chatting with agents. + + This method creates a REPL (Read-Eval-Print Loop) that allows users to: + - Chat with agents using @mentions + - See available agents and their descriptions + - Exit the session using 'exit' or 'quit' + - Get help using 'help' or '?' + """ + if not self.interactive: + raise InteractiveGroupChatError( + "Interactive mode is not enabled. Initialize with interactive=True" + ) + + print(f"\nWelcome to {self.name}!") + print(f"Description: {self.description}") + print( + f"Current speaker function: {self.get_current_speaker_function()}" + ) + print("\nAvailable agents:") + for name, agent in self.agent_map.items(): + if isinstance(agent, Agent): + print( + f"- @{name}: {agent.system_prompt.splitlines()[0]}" + ) + else: + print(f"- @{name}: Custom callable function") + + print("\nCommands:") + print("- Type 'help' or '?' for help") + print("- Type 'exit' or 'quit' to end the session") + print("- Type 'speaker' to change speaker function") + print("- Use @agent_name to mention agents") + print("\nStart chatting:") + + while True: + try: + # Get user input + user_input = input("\nYou: ").strip() + + # Handle special commands + if user_input.lower() in ["exit", "quit"]: + print("Goodbye!") + break + + if user_input.lower() in ["help", "?"]: + print("\nHelp:") + print("1. Mention agents using @agent_name") + print( + "2. You can mention multiple agents in one task" + ) + print("3. Available agents:") + for name in self.agent_map: + print(f" - @{name}") + print( + "4. Type 'speaker' to change speaker function" + ) + print( + "5. Type 'exit' or 'quit' to end the session" + ) + continue + + if user_input.lower() == "speaker": + print( + f"\nCurrent speaker function: {self.get_current_speaker_function()}" + ) + print("Available speaker functions:") + for i, func_name in enumerate( + self.get_available_speaker_functions(), 1 + ): + print(f" {i}. {func_name}") + + try: + choice = input( + "\nEnter the number or name of the speaker function: " + ).strip() + + # Try to parse as number first + try: + func_index = int(choice) - 1 + if ( + 0 + <= func_index + < len( + self.get_available_speaker_functions() + ) + ): + selected_func = self.get_available_speaker_functions()[ + func_index + ] + else: + print( + "Invalid number. Please try again." + ) + continue + except ValueError: + # Try to parse as name + selected_func = choice + + self.set_speaker_function(selected_func) + print( + f"Speaker function changed to: {self.get_current_speaker_function()}" + ) + + except InvalidSpeakerFunctionError as e: + print(f"Error: {e}") + except Exception as e: + print(f"An error occurred: {e}") + continue + + if not user_input: + continue + + # Process the task and get responses + try: + self.run(user_input) + print("\nChat:") + # print(response) + + except NoMentionedAgentsError: + print( + "\nError: Please mention at least one agent using @agent_name" + ) + except AgentNotFoundError as e: + print(f"\nError: {str(e)}") + except Exception as e: + print(f"\nAn error occurred: {str(e)}") + + except KeyboardInterrupt: + print("\nSession terminated by user. Goodbye!") + break + except Exception as e: + print(f"\nAn unexpected error occurred: {str(e)}") + print( + "The session will continue. You can type 'exit' to end it." + ) + def _validate_speaker_function(self) -> None: """ Validates the speaker function. @@ -287,6 +621,7 @@ IMPORTANT: You are part of a collaborative group chat where you can interact wit 2. ACKNOWLEDGE: Reference and acknowledge what other agents have said 3. BUILD UPON: Add your perspective while building upon their insights 4. MENTION: Use @agent_name to call on other agents when needed +5. COMPLETE: Acknowledge when your part is done and what still needs to be done HOW TO MENTION OTHER AGENTS: - Use @agent_name to mention another agent in your response @@ -325,24 +660,33 @@ COLLABORATION GUIDELINES: - ASK CLARIFYING QUESTIONS if you need more information from other agents - DELEGATE appropriately: "Let me ask @expert_agent to verify this" or "@specialist, can you elaborate on this point?" +TASK COMPLETION GUIDELINES: +- ACKNOWLEDGE when you are done with your part of the task +- CLEARLY STATE what still needs to be done before the overall task is finished +- If you mention other agents, explain what specific input you need from them +- Use phrases like "I have completed [specific part]" or "The task still requires [specific actions]" +- Provide a clear status update: "My analysis is complete. The task now needs @writer to create content and @reviewer to validate the approach." + RESPONSE STRUCTURE: 1. ACKNOWLEDGE: "I've reviewed the responses from @agent1 and @agent2..." 2. BUILD: "Building on @agent1's analysis of the data..." 3. CONTRIBUTE: "From my perspective, I would add..." 4. COLLABORATE: "To get a complete picture, let me ask @agent3 to..." -5. SYNTHESIZE: "Combining our insights, the key findings are..." +5. COMPLETE: "I have completed [my part]. The task still requires [specific next steps]" +6. SYNTHESIZE: "Combining our insights, the key findings are..." EXAMPLES OF GOOD COLLABORATION: -- "I've reviewed @analyst's data analysis and @researcher's market insights. The data shows strong growth potential, and I agree with @researcher that we should focus on emerging markets. Let me add that from a content perspective, we should @writer to create targeted messaging for these markets." -- "Building on @researcher's findings about customer behavior, I can see that @analyst's data supports this trend. To get a complete understanding, let me ask @writer to help us craft messaging that addresses these specific customer needs." +- "I've reviewed @analyst's data analysis and @researcher's market insights. The data shows strong growth potential, and I agree with @researcher that we should focus on emerging markets. Let me add that from a content perspective, we should @writer to create targeted messaging for these markets. I have completed my market analysis. The task now requires @writer to develop content and @reviewer to validate our approach." +- "Building on @researcher's findings about customer behavior, I can see that @analyst's data supports this trend. To get a complete understanding, let me ask @writer to help us craft messaging that addresses these specific customer needs. My data analysis is complete. The task still needs @writer to create messaging and @reviewer to approve the final strategy." AVOID: - Ignoring other agents' responses - Repeating what others have already said - Making assumptions without consulting relevant experts - Responding in isolation without considering the group's collective knowledge +- Not acknowledging task completion status -Remember: You are part of a team. Your response should reflect that you've read, understood, and built upon the contributions of others. +Remember: You are part of a team. Your response should reflect that you've read, understood, and are building upon the contributions of others, and clearly communicate your task completion status. """ # Update the agent's system prompt @@ -438,6 +782,12 @@ Remember: You are part of a team. Your response should reflect that you've read, ) return sorted_agents + elif self.speaker_function == random_dynamic_speaker: + # For dynamic speaker, we need to handle it differently + # The dynamic speaker will be called during the run method + # For now, just return the original order + return mentioned_agents + else: # Custom speaker function # For custom functions, we'll use the first agent returned @@ -460,120 +810,12 @@ Remember: You are part of a team. Your response should reflect that you've read, # Fallback to original order return mentioned_agents - def set_speaker_function( + def run( self, - speaker_function: Callable, - speaker_state: Optional[dict] = None, - ) -> None: - """ - Set a custom speaker function and optional state. - - Args: - speaker_function: Function that determines speaking order - speaker_state: Optional state for the speaker function - """ - self.speaker_function = speaker_function - if speaker_state: - self.speaker_state.update(speaker_state) - self._validate_speaker_function() - logger.info( - f"Speaker function updated to: {speaker_function.__name__}" - ) - - def set_priorities(self, priorities: dict) -> None: - """ - Set agent priorities for priority-based speaking order. - - Args: - priorities: Dictionary mapping agent names to priority weights - """ - self.speaker_state["priorities"] = priorities - logger.info(f"Agent priorities set: {priorities}") - - def start_interactive_session(self): - """ - Start an interactive terminal session for chatting with agents. - - This method creates a REPL (Read-Eval-Print Loop) that allows users to: - - Chat with agents using @mentions - - See available agents and their descriptions - - Exit the session using 'exit' or 'quit' - - Get help using 'help' or '?' - """ - if not self.interactive: - raise InteractiveGroupChatError( - "Interactive mode is not enabled. Initialize with interactive=True" - ) - - print(f"\nWelcome to {self.name}!") - print(f"Description: {self.description}") - print("\nAvailable agents:") - for name, agent in self.agent_map.items(): - if isinstance(agent, Agent): - print( - f"- @{name}: {agent.system_prompt.splitlines()[0]}" - ) - else: - print(f"- @{name}: Custom callable function") - - print("\nCommands:") - print("- Type 'help' or '?' for help") - print("- Type 'exit' or 'quit' to end the session") - print("- Use @agent_name to mention agents") - print("\nStart chatting:") - - while True: - try: - # Get user input - user_input = input("\nYou: ").strip() - - # Handle special commands - if user_input.lower() in ["exit", "quit"]: - print("Goodbye!") - break - - if user_input.lower() in ["help", "?"]: - print("\nHelp:") - print("1. Mention agents using @agent_name") - print( - "2. You can mention multiple agents in one task" - ) - print("3. Available agents:") - for name in self.agent_map: - print(f" - @{name}") - print( - "4. Type 'exit' or 'quit' to end the session" - ) - continue - - if not user_input: - continue - - # Process the task and get responses - try: - self.run(user_input) - print("\nChat:") - # print(response) - - except NoMentionedAgentsError: - print( - "\nError: Please mention at least one agent using @agent_name" - ) - except AgentNotFoundError as e: - print(f"\nError: {str(e)}") - except Exception as e: - print(f"\nAn error occurred: {str(e)}") - - except KeyboardInterrupt: - print("\nSession terminated by user. Goodbye!") - break - except Exception as e: - print(f"\nAn unexpected error occurred: {str(e)}") - print( - "The session will continue. You can type 'exit' to end it." - ) - - def run(self, task: str) -> str: + task: str, + img: Optional[str] = None, + imgs: Optional[List[str]] = None, + ) -> str: """ Process a task and get responses from mentioned agents. If interactive mode is enabled, this will be called by start_interactive_session(). @@ -591,31 +833,171 @@ Remember: You are part of a team. Your response should reflect that you've read, # Add user task to conversation self.conversation.add(role="User", content=task) - # Determine speaking order using speaker function - speaking_order = self._get_speaking_order( - mentioned_agents - ) - logger.info( - f"Speaking order determined: {speaking_order}" - ) + # Handle dynamic speaker function differently + if self.speaker_function == random_dynamic_speaker: + # Get strategy from speaker state (default to sequential) + strategy = self.speaker_state.get( + "strategy", "sequential" + ) - # Get responses from mentioned agents in the determined order - for agent_name in speaking_order: - agent = self.agent_map.get(agent_name) - if not agent: - raise AgentNotFoundError( - f"Agent '{agent_name}' not found" + # For dynamic speaker, we'll determine the next speaker after each response + # Track which agents have spoken to ensure all get a chance + spoken_agents = set() + last_response = "" + max_iterations = ( + len(mentioned_agents) * 3 + ) # Allow more iterations for parallel + iteration = 0 + + while iteration < max_iterations and len( + spoken_agents + ) < len(mentioned_agents): + # Determine next speaker(s) using dynamic function + next_speakers = self.speaker_function( + mentioned_agents, # Use all mentioned agents, not remaining_agents + last_response, + strategy=strategy, + **self.speaker_state, ) - try: - # Get the complete conversation history - context = ( - self.conversation.return_history_as_string() + # Handle both single agent and multiple agents + if isinstance(next_speakers, str): + next_speakers = [next_speakers] + + # Filter out invalid agents + valid_next_speakers = [ + agent + for agent in next_speakers + if agent in mentioned_agents + ] + + if not valid_next_speakers: + # If no valid mentions found, randomly select from unspoken agents + unspoken_agents = [ + agent + for agent in mentioned_agents + if agent not in spoken_agents + ] + if unspoken_agents: + valid_next_speakers = [ + random.choice(unspoken_agents) + ] + else: + # All agents have spoken, break the loop + break + + # Process agents based on strategy + if strategy == "sequential": + # Process one agent at a time + for next_speaker in valid_next_speakers: + if next_speaker in spoken_agents: + continue # Skip if already spoken + + response = self._get_agent_response( + next_speaker, img, imgs + ) + if response: + last_response = response + spoken_agents.add(next_speaker) + break # Only process one agent in sequential mode + + elif strategy == "parallel": + # Process all mentioned agents in parallel + import concurrent.futures + + # Get responses from all valid agents + responses = [] + with concurrent.futures.ThreadPoolExecutor() as executor: + future_to_agent = { + executor.submit( + self._get_agent_response, + agent, + img, + imgs, + ): agent + for agent in valid_next_speakers + if agent not in spoken_agents + } + + for ( + future + ) in concurrent.futures.as_completed( + future_to_agent + ): + agent = future_to_agent[future] + try: + response = future.result() + if response: + responses.append(response) + spoken_agents.add(agent) + except Exception as e: + logger.error( + f"Error getting response from {agent}: {e}" + ) + + # Combine responses for next iteration + if responses: + last_response = "\n\n".join(responses) + + iteration += 1 + else: + # For non-dynamic speaker functions, use the original logic + speaking_order = self._get_speaking_order( + mentioned_agents + ) + logger.info( + f"Speaking order determined: {speaking_order}" + ) + + # Get responses from mentioned agents in the determined order + for agent_name in speaking_order: + response = self._get_agent_response( + agent_name, img, imgs ) - # Get response from agent - if isinstance(agent, Agent): - collaborative_task = f"""{context} + return history_output_formatter( + self.conversation, self.output_type + ) + + except InteractiveGroupChatError as e: + logger.error(f"GroupChat error: {e}") + raise + except Exception as e: + logger.error(f"Unexpected error: {e}") + raise InteractiveGroupChatError( + f"Unexpected error occurred: {str(e)}" + ) + + def _get_agent_response( + self, + agent_name: str, + img: Optional[str] = None, + imgs: Optional[List[str]] = None, + ) -> Optional[str]: + """ + Get response from a specific agent. + + Args: + agent_name: Name of the agent to get response from + img: Optional image for the task + imgs: Optional list of images for the task + + Returns: + The agent's response or None if error + """ + agent = self.agent_map.get(agent_name) + if not agent: + raise AgentNotFoundError( + f"Agent '{agent_name}' not found" + ) + + try: + # Get the complete conversation history + context = self.conversation.return_history_as_string() + + # Get response from agent + if isinstance(agent, Agent): + collaborative_task = f"""{context} COLLABORATIVE TASK: Please respond to the latest task as {agent_name}. @@ -626,38 +1008,56 @@ IMPORTANT INSTRUCTIONS: 4. If you need input from other agents, mention them using @agent_name 5. Provide your unique expertise while showing you understand the group's collective knowledge -Remember: You are part of a collaborative team. Your response should demonstrate that you've read, understood, and are building upon the contributions of others.""" +TASK COMPLETION GUIDELINES: +- Acknowledge when you are done with your part of the task +- Clearly state what still needs to be done before the overall task is finished +- If you mention other agents, explain what specific input you need from them +- Use phrases like "I have completed [specific part]" or "The task still requires [specific actions]" - response = agent.run(task=collaborative_task) - else: - # For callable functions - response = agent(context) +Remember: You are part of a collaborative team. Your response should demonstrate that you've read, understood, and are building upon the contributions of others.""" - # Add response to conversation - if response and not response.isspace(): - self.conversation.add( - role=agent_name, content=response - ) - logger.info(f"Agent {agent_name} responded") + response = agent.run( + task=collaborative_task, + img=img, + imgs=imgs, + ) + else: + # For callable functions + response = agent(context) - except Exception as e: - logger.error( - f"Error getting response from {agent_name}: {e}" - ) - self.conversation.add( - role=agent_name, - content=f"Error: Unable to generate response - {str(e)}", - ) + # Add response to conversation + if response and not response.isspace(): + self.conversation.add( + role=agent_name, content=response + ) + logger.info(f"Agent {agent_name} responded") + return response - return history_output_formatter( - self.conversation, self.output_type + except Exception as e: + logger.error( + f"Error getting response from {agent_name}: {e}" ) + self.conversation.add( + role=agent_name, + content=f"Error: Unable to generate response - {str(e)}", + ) + return f"Error: Unable to generate response - {str(e)}" - except InteractiveGroupChatError as e: - logger.error(f"GroupChat error: {e}") - raise - except Exception as e: - logger.error(f"Unexpected error: {e}") - raise InteractiveGroupChatError( - f"Unexpected error occurred: {str(e)}" + return None + + def set_dynamic_strategy(self, strategy: str) -> None: + """ + Set the strategy for the random-dynamic-speaker function. + + Args: + strategy: Either "sequential" or "parallel" + - "sequential": Process one agent at a time based on @mentions + - "parallel": Process all mentioned agents simultaneously + """ + if strategy not in ["sequential", "parallel"]: + raise ValueError( + "Strategy must be either 'sequential' or 'parallel'" ) + + self.speaker_state["strategy"] = strategy + logger.info(f"Dynamic speaker strategy set to: {strategy}") diff --git a/swarms/structs/ma_utils.py b/swarms/structs/ma_utils.py index b47080b8..1cf1e0fb 100644 --- a/swarms/structs/ma_utils.py +++ b/swarms/structs/ma_utils.py @@ -86,6 +86,7 @@ models = [ "o4-mini", "o3", "gpt-4.1", + "groq/llama-3.1-8b-instant", "gpt-4.1-nano", ] diff --git a/swarms/structs/swarm_router.py b/swarms/structs/swarm_router.py index 4cfe119e..3452343b 100644 --- a/swarms/structs/swarm_router.py +++ b/swarms/structs/swarm_router.py @@ -182,6 +182,7 @@ class SwarmRouter: list_all_agents: bool = False, conversation: Any = None, agents_config: Optional[Dict[Any, Any]] = None, + speaker_function: str = None, *args, **kwargs, ): @@ -208,6 +209,7 @@ class SwarmRouter: self.list_all_agents = list_all_agents self.conversation = conversation self.agents_config = agents_config + self.speaker_function = speaker_function # Reliability check self.reliability_check() @@ -358,6 +360,7 @@ class SwarmRouter: agents=self.agents, max_loops=self.max_loops, output_type=self.output_type, + speaker_function=self.speaker_function, ) elif self.swarm_type == "DeepResearchSwarm": diff --git a/swarms/utils/litellm_wrapper.py b/swarms/utils/litellm_wrapper.py index 01392b34..063e6ce3 100644 --- a/swarms/utils/litellm_wrapper.py +++ b/swarms/utils/litellm_wrapper.py @@ -151,6 +151,8 @@ class LiteLLM: retries # Add retries for better reliability ) + litellm.drop_params = True + def output_for_tools(self, response: any): if self.mcp_call is True: out = response.choices[0].message.tool_calls[0].function