From 9068b7f061b09cd60e3a2c950e1df4415e8a2aa8 Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Mon, 8 Sep 2025 16:29:37 -0700 Subject: [PATCH] [DOCS][Cleanup Swarms API Un-used docs which are all on docs.swarms.ai] --- docs/mkdocs.yml | 36 - docs/swarms/examples/swarms_api_finance.md | 127 -- docs/swarms/examples/swarms_api_medical.md | 128 -- docs/swarms_cloud/add_agent.md | 56 - docs/swarms_cloud/agent_api.md | 608 ---------- docs/swarms_cloud/agent_rearrange.md | 204 ---- docs/swarms_cloud/api_clients.md | 242 ---- docs/swarms_cloud/api_pricing.md | 198 --- docs/swarms_cloud/auto.md | 55 - docs/swarms_cloud/auto_swarm_builder.md | 46 - docs/swarms_cloud/best_practices.md | 170 --- docs/swarms_cloud/chinese_api_pricing.md | 195 --- docs/swarms_cloud/concurrent_workflow.md | 214 ---- docs/swarms_cloud/group_chat.md | 189 --- docs/swarms_cloud/hierarchical_swarm.md | 252 ---- docs/swarms_cloud/index.md | 0 docs/swarms_cloud/launch.md | 369 ------ docs/swarms_cloud/majority_voting.md | 249 ---- docs/swarms_cloud/mcp.md | 342 ------ docs/swarms_cloud/mcs_api.md | 727 ----------- docs/swarms_cloud/mixture_of_agents.md | 222 ---- docs/swarms_cloud/multi_agent_router.md | 211 ---- docs/swarms_cloud/production_deployment.md | 319 ----- docs/swarms_cloud/python_client.md | 779 ------------ docs/swarms_cloud/quickstart.md | 1165 ------------------ docs/swarms_cloud/rate_limits.md | 196 --- docs/swarms_cloud/rust_client.md | 732 ----------- docs/swarms_cloud/sequential_workflow.md | 214 ---- docs/swarms_cloud/subscription_tiers.md | 128 -- docs/swarms_cloud/swarm_types.md | 28 - docs/swarms_cloud/swarms_api.md | 1271 -------------------- docs/swarms_cloud/swarms_api_tools.md | 382 ------ 32 files changed, 10054 deletions(-) delete mode 100644 docs/swarms/examples/swarms_api_finance.md delete mode 100644 docs/swarms/examples/swarms_api_medical.md delete mode 100644 docs/swarms_cloud/add_agent.md delete mode 100644 docs/swarms_cloud/agent_api.md delete mode 100644 docs/swarms_cloud/agent_rearrange.md delete mode 100644 docs/swarms_cloud/api_clients.md delete mode 100644 docs/swarms_cloud/api_pricing.md delete mode 100644 docs/swarms_cloud/auto.md delete mode 100644 docs/swarms_cloud/auto_swarm_builder.md delete mode 100644 docs/swarms_cloud/best_practices.md delete mode 100644 docs/swarms_cloud/chinese_api_pricing.md delete mode 100644 docs/swarms_cloud/concurrent_workflow.md delete mode 100644 docs/swarms_cloud/group_chat.md delete mode 100644 docs/swarms_cloud/hierarchical_swarm.md delete mode 100644 docs/swarms_cloud/index.md delete mode 100644 docs/swarms_cloud/launch.md delete mode 100644 docs/swarms_cloud/majority_voting.md delete mode 100644 docs/swarms_cloud/mcp.md delete mode 100644 docs/swarms_cloud/mcs_api.md delete mode 100644 docs/swarms_cloud/mixture_of_agents.md delete mode 100644 docs/swarms_cloud/multi_agent_router.md delete mode 100644 docs/swarms_cloud/production_deployment.md delete mode 100644 docs/swarms_cloud/python_client.md delete mode 100644 docs/swarms_cloud/quickstart.md delete mode 100644 docs/swarms_cloud/rate_limits.md delete mode 100644 docs/swarms_cloud/rust_client.md delete mode 100644 docs/swarms_cloud/sequential_workflow.md delete mode 100644 docs/swarms_cloud/subscription_tiers.md delete mode 100644 docs/swarms_cloud/swarm_types.md delete mode 100644 docs/swarms_cloud/swarms_api.md delete mode 100644 docs/swarms_cloud/swarms_api_tools.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1da89ac5..0c786b66 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -336,12 +336,6 @@ nav: - Social Media: - Twitter: "swarms_tools/twitter.md" - # - Memory: - # - Overview: "swarms_memory/index.md" - # - Memory Systems: - # - ChromaDB: "swarms_memory/chromadb.md" - # - Pinecone: "swarms_memory/pinecone.md" - # - Faiss: "swarms_memory/faiss.md" - Deployment Solutions: - Overview: "deployment_solutions/overview.md" @@ -399,15 +393,6 @@ nav: - # - Swarms Tools: - # - Agent with Yahoo Finance: "swarms/examples/yahoo_finance.md" - # - Twitter Agents: "swarms_tools/twitter.md" - # - Blockchain Agents: - # - Agent with HTX + CoinGecko: "swarms/examples/swarms_tools_htx.md" - # - Agent with HTX + CoinGecko Function Calling: "swarms/examples/swarms_tools_htx_gecko.md" - # - Lumo: "swarms/examples/lumo.md" - # - Quant Crypto Agent: "swarms/examples/quant_crypto_agent.md" - - Advanced Examples: - Multi-Agent Architectures: - HierarchicalSwarm Examples: "swarms/examples/hierarchical_swarm_example.md" @@ -450,27 +435,6 @@ nav: - Overview: "swarms_cloud/migration.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" - # - Swarm Types: - # - AgentRearrange: "swarms_cloud/agent_rearrange.md" - # - MixtureOfAgents: "swarms_cloud/mixture_of_agents.md" - # - SequentialWorkflow: "swarms_cloud/sequential_workflow.md" - # - ConcurrentWorkflow: "swarms_cloud/concurrent_workflow.md" - # - GroupChat: "swarms_cloud/group_chat.md" - # - MultiAgentRouter: "swarms_cloud/multi_agent_router.md" - # - HierarchicalSwarm: "swarms_cloud/hierarchical_swarm.md" - # - MajorityVoting: "swarms_cloud/majority_voting.md" - # # - AutoSwarmBuilder: "swarms_cloud/auto_swarm_builder.md" - # # - Auto: "swarms_cloud/auto.md" - # - Examples: - # - Medical Swarm: "swarms/examples/swarms_api_medical.md" - # - Finance Swarm: "swarms/examples/swarms_api_finance.md" - - Swarms Marketplace: - Overview: "swarms_platform/index.md" - Marketplace: diff --git a/docs/swarms/examples/swarms_api_finance.md b/docs/swarms/examples/swarms_api_finance.md deleted file mode 100644 index 9a3b2ba3..00000000 --- a/docs/swarms/examples/swarms_api_finance.md +++ /dev/null @@ -1,127 +0,0 @@ - -# Finance Swarm Example - -1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys) -2. Create a `.env` file in the root directory and add your API key: - -```bash -SWARMS_API_KEY= -``` - -3. Create a Python script to create and trigger the financial swarm: - - -```python -import os -import requests -from dotenv import load_dotenv -import json - -load_dotenv() - -# Retrieve API key securely from .env -API_KEY = os.getenv("SWARMS_API_KEY") -BASE_URL = "https://api.swarms.world" - -# Headers for secure API communication -headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} - -def create_financial_swarm(equity_data: str): - """ - Constructs and triggers a full-stack financial swarm consisting of three agents: - Equity Analyst, Risk Assessor, and Market Advisor. - Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. - """ - - payload = { - "swarm_name": "Enhanced Financial Analysis Swarm", - "description": "A swarm of agents specialized in performing comprehensive financial analysis, risk assessment, and market recommendations.", - "agents": [ - { - "agent_name": "Equity Analyst", - "description": "Agent specialized in analyzing equities data to provide insights on stock performance and valuation.", - "system_prompt": ( - "You are an experienced equity analyst with expertise in financial markets and stock valuation. " - "Your role is to analyze the provided equities data, including historical performance, financial statements, and market trends. " - "Provide a detailed analysis of the stock's potential, including valuation metrics and growth prospects. " - "Consider macroeconomic factors, industry trends, and company-specific news. Your analysis should be clear, actionable, and well-supported by data." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 4000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Risk Assessor", - "description": "Agent responsible for evaluating the risks associated with equity investments.", - "system_prompt": ( - "You are a certified risk management professional with expertise in financial risk assessment. " - "Your task is to evaluate the risks associated with the provided equities data, including market risk, credit risk, and operational risk. " - "Provide a comprehensive risk analysis, including potential scenarios and their impact on investment performance. " - "Your output should be detailed, reliable, and compliant with current risk management standards." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.2, - "auto_generate_prompt": False - }, - { - "agent_name": "Market Advisor", - "description": "Agent dedicated to suggesting investment strategies based on market conditions and equity analysis.", - "system_prompt": ( - "You are a knowledgeable market advisor with expertise in investment strategies and portfolio management. " - "Based on the analysis provided by the Equity Analyst and the risk assessment, your task is to recommend a comprehensive investment strategy. " - "Your suggestions should include asset allocation, diversification strategies, and considerations for market conditions. " - "Explain the rationale behind each recommendation and reference relevant market data where applicable. " - "Your recommendations should be reliable, detailed, and clearly prioritized based on risk and return." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 5000, - "temperature": 0.3, - "auto_generate_prompt": False - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": equity_data, - } - - # Payload includes the equity data as the task to be processed by the swarm - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload, - ) - - if response.status_code == 200: - print("Swarm successfully executed!") - return json.dumps(response.json(), indent=4) - else: - print(f"Error {response.status_code}: {response.text}") - return None - - -# Example Equity Data for the Swarm to analyze -if __name__ == "__main__": - equity_data = ( - "Analyze the equity data for Company XYZ, which has shown a 15% increase in revenue over the last quarter, " - "with a P/E ratio of 20 and a market cap of $1 billion. Consider the current market conditions and potential risks." - ) - - financial_output = create_financial_swarm(equity_data) - print(financial_output) -``` - -4. Run the script: - -```bash -python financial_swarm.py -``` - diff --git a/docs/swarms/examples/swarms_api_medical.md b/docs/swarms/examples/swarms_api_medical.md deleted file mode 100644 index 00fb89e9..00000000 --- a/docs/swarms/examples/swarms_api_medical.md +++ /dev/null @@ -1,128 +0,0 @@ -# Medical Swarm Example - -1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys) -2. Create a `.env` file in the root directory and add your API key: - -```bash -SWARMS_API_KEY= -``` - -3. Create a Python script to create and trigger the medical swarm: - -```python -import os -import requests -from dotenv import load_dotenv -import json - -load_dotenv() - -# Retrieve API key securely from .env -API_KEY = os.getenv("SWARMS_API_KEY") -BASE_URL = "https://api.swarms.world" - -# Headers for secure API communication -headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} - -def create_medical_swarm(patient_case: str): - """ - Constructs and triggers a full-stack medical swarm consisting of three agents: - Diagnostic Specialist, Medical Coder, and Treatment Advisor. - Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability. - """ - - payload = { - "swarm_name": "Enhanced Medical Diagnostic Swarm", - "description": "A swarm of agents specialized in performing comprehensive medical diagnostics, analysis, and coding.", - "agents": [ - { - "agent_name": "Diagnostic Specialist", - "description": "Agent specialized in analyzing patient history, symptoms, lab results, and imaging data to produce accurate diagnoses.", - "system_prompt": ( - "You are an experienced, board-certified medical diagnostician with over 20 years of clinical practice. " - "Your role is to analyze all available patient information—including history, symptoms, lab tests, and imaging results—" - "with extreme attention to detail and clinical nuance. Provide a comprehensive differential diagnosis considering " - "common, uncommon, and rare conditions. Always cross-reference clinical guidelines and evidence-based medicine. " - "Explain your reasoning step by step and provide a final prioritized list of potential diagnoses along with their likelihood. " - "Consider patient demographics, comorbidities, and risk factors. Your diagnosis should be reliable, clear, and actionable." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 4000, - "temperature": 0.3, - "auto_generate_prompt": False - }, - { - "agent_name": "Medical Coder", - "description": "Agent responsible for translating medical diagnoses and procedures into accurate standardized medical codes (ICD-10, CPT, etc.).", - "system_prompt": ( - "You are a certified and experienced medical coder, well-versed in ICD-10, CPT, and other coding systems. " - "Your task is to convert detailed medical diagnoses and treatment procedures into precise, standardized codes. " - "Consider all aspects of the clinical documentation including severity, complications, and comorbidities. " - "Provide clear explanations for the codes chosen, referencing the latest coding guidelines and payer policies where relevant. " - "Your output should be comprehensive, reliable, and fully compliant with current medical coding standards." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 3000, - "temperature": 0.2, - "auto_generate_prompt": False - }, - { - "agent_name": "Treatment Advisor", - "description": "Agent dedicated to suggesting evidence-based treatment options, including pharmaceutical and non-pharmaceutical interventions.", - "system_prompt": ( - "You are a highly knowledgeable medical treatment specialist with expertise in the latest clinical guidelines and research. " - "Based on the diagnostic conclusions provided, your task is to recommend a comprehensive treatment plan. " - "Your suggestions should include first-line therapies, potential alternative treatments, and considerations for patient-specific factors " - "such as allergies, contraindications, and comorbidities. Explain the rationale behind each treatment option and reference clinical guidelines where applicable. " - "Your recommendations should be reliable, detailed, and clearly prioritized based on efficacy and safety." - ), - "model_name": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 5000, - "temperature": 0.3, - "auto_generate_prompt": False - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": patient_case, - } - - # Payload includes the patient case as the task to be processed by the swar - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload, - ) - - if response.status_code == 200: - print("Swarm successfully executed!") - return json.dumps(response.json(), indent=4) - else: - print(f"Error {response.status_code}: {response.text}") - return None - - -# Example Patient Task for the Swarm to diagnose and analyze -if __name__ == "__main__": - patient_case = ( - "Patient is a 55-year-old male presenting with severe chest pain, shortness of breath, elevated blood pressure, " - "nausea, and a family history of cardiovascular disease. Blood tests show elevated troponin levels, and EKG indicates ST-segment elevations. " - "The patient is currently unstable. Provide a detailed diagnosis, coding, and treatment plan." - ) - - diagnostic_output = create_medical_swarm(patient_case) - print(diagnostic_output) -``` - -4. Run the script: - -```bash -python medical_swarm.py -``` \ No newline at end of file diff --git a/docs/swarms_cloud/add_agent.md b/docs/swarms_cloud/add_agent.md deleted file mode 100644 index 6bd4f507..00000000 --- a/docs/swarms_cloud/add_agent.md +++ /dev/null @@ -1,56 +0,0 @@ -# Publishing an Agent to Agent Marketplace - -## Requirements - -- `swarms-cloud` package with `pip3 install -U swarms-cloud` - -- Onboarding Process with `swarms-cloud onboarding` - -- A Dockerfile `Dockerfile` containing the API of your agent code with FastAPI - -- A YAML file for configuration `agent.yaml` - -## Deployment YAML -```yaml - -# Agent metadata and description -agent_name: "example-agent" # The name of the agent -description: "This agent performs financial data analysis." # A brief description of the agent's purpose -version: "v1.0" # The version number of the agent -author: "Agent Creator Name" # The name of the person or entity that created the agent -contact_email: "creator@example.com" # The email address for contacting the agent's creator -tags: - - "financial" # Tag indicating the agent is related to finance - - "data-analysis" # Tag indicating the agent performs data analysis - - "agent" # Tag indicating this is an agent - - -# Deployment configuration -deployment_config: - # Dockerfile configuration - dockerfile_path: "./Dockerfile" # The path to the Dockerfile for building the agent's image - dockerfile_port: 8080 # The port number the agent will listen on - - # Resource allocation for the agent - resources: - cpu: 2 # Number of CPUs allocated to the agent - memory: "2Gi" # Memory allocation for the agent in gigabytes - max_instances: 5 # Maximum number of instances to scale up to - min_instances: 1 # Minimum number of instances to keep running - timeout: 300s # Request timeout setting in seconds - - # Autoscaling configuration - autoscaling: - max_concurrency: 80 # Maximum number of requests the agent can handle concurrently - target_utilization: 0.6 # CPU utilization target for auto-scaling - - # Environment variables for the agent - environment_variables: - DATABASE_URL: "postgres://user:password@db-url" # URL for the database connection - API_KEY: "your-secret-api-key" # API key for authentication - LOG_LEVEL: "info" # Log level for the agent - - # Secrets configuration - secrets: - SECRET_NAME_1: "projects/my-project/secrets/my-secret/versions/latest" # Path to a secret -``` \ No newline at end of file diff --git a/docs/swarms_cloud/agent_api.md b/docs/swarms_cloud/agent_api.md deleted file mode 100644 index aeab0d98..00000000 --- a/docs/swarms_cloud/agent_api.md +++ /dev/null @@ -1,608 +0,0 @@ -# Agent API - -The Swarms.ai Agent API provides powerful endpoints for running individual AI agents and batch agent operations. This documentation explains how to use these endpoints for effective agent-based task execution. - -## Getting Started - -To use the Agent API, you'll need a Swarms.ai API key: - -1. Go to [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys) -2. Generate a new API key -3. Store your API key securely - it won't be shown again - -```python -import os -import requests -from dotenv import load_dotenv - -# Load API key from environment -load_dotenv() -API_KEY = os.getenv("SWARMS_API_KEY") -BASE_URL = "https://api.swarms.world" - -# Configure headers with your API key -headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" -} -``` - -## Individual Agent API - -The Individual Agent API allows you to run a single agent with a specific configuration and task. - -### Agent Configuration (`AgentSpec`) - -The `AgentSpec` class defines the configuration for an individual agent. - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `agent_name` | string | Required | Unique name identifying the agent and its functionality | -| `description` | string | None | Detailed explanation of the agent's purpose and capabilities | -| `system_prompt` | string | None | Initial instructions guiding the agent's behavior and responses | -| `model_name` | string | "gpt-4o-mini" | The AI model used by the agent (e.g., gpt-4o, gpt-4o-mini, openai/o3-mini) | -| `auto_generate_prompt` | boolean | false | Whether the agent should automatically create prompts based on task requirements | -| `max_tokens` | integer | 8192 | Maximum number of tokens the agent can generate in its responses | -| `temperature` | float | 0.5 | Controls output randomness (lower values = more deterministic responses) | -| `role` | string | "worker" | The agent's role within a swarm, influencing its behavior and interactions | -| `max_loops` | integer | 1 | Maximum number of times the agent can repeat its task for iterative processing | -| `tools_dictionary` | array | None | Dictionary of tools the agent can use to complete its task | -| `mcp_url` | string | None | URL for the MCP server that the agent can connect to | - -### Agent Completion - -The `AgentCompletion` class combines an agent configuration with a specific task. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `agent_config` | AgentSpec | Configuration of the agent to be completed | -| `task` | string | The task to be completed by the agent | -| `history` | Optional[Union[Dict[Any, Any], List[Dict[str, str]]]] | The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects. | - -### Single Agent Endpoint - -**Endpoint:** `POST /v1/agent/completions` - -Run a single agent with a specific configuration and task. - -#### Request - -```python -def run_single_agent(agent_config, task): - """ - Run a single agent with the AgentCompletion format. - - Args: - agent_config: Dictionary containing agent configuration - task: String describing the task for the agent - - Returns: - Dictionary containing the agent's response - """ - payload = { - "agent_config": agent_config, - "task": task - } - - try: - response = requests.post( - f"{BASE_URL}/v1/agent/completions", - headers=headers, - json=payload - ) - response.raise_for_status() - return response.json() - except requests.exceptions.RequestException as e: - print(f"Error making request: {e}") - return None -``` - -#### Example Usage - -```python -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. " - "Focus on accuracy, clarity, and actionable recommendations." - ), - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 2, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": False, -} - -task = "Analyze the impact of artificial intelligence on healthcare delivery and provide a comprehensive report with key findings and recommendations." - -result = run_single_agent(agent_config, task) -print(result) -``` - -#### Response Structure - -```json -{ - "id": "agent-6a8b9c0d1e2f3g4h5i6j7k8l9m0n", - "success": true, - "name": "Research Analyst", - "description": "An expert in analyzing and synthesizing research data", - "temperature": 0.5, - "outputs": { - "content": "# Impact of Artificial Intelligence on Healthcare Delivery\n\n## Executive Summary\n...", - "role": "assistant" - }, - "usage": { - "input_tokens": 1250, - "output_tokens": 3822, - "total_tokens": 5072 - }, - "timestamp": "2025-05-10T18:35:29.421Z" -} -``` - -## Batch Agent API - -The Batch Agent API allows you to run multiple agents in parallel, each with different configurations and tasks. - -### Batch Agent Endpoint - -**Endpoint:** `POST /v1/agent/batch/completions` - -Run multiple agents with different configurations and tasks in a single API call. - -#### Request - -```python -def run_batch_agents(agent_completions): - """ - Run multiple agents in batch. - - Args: - agent_completions: List of dictionaries, each containing agent_config and task - - Returns: - List of agent responses - """ - try: - response = requests.post( - f"{BASE_URL}/v1/agent/batch/completions", - headers=headers, - json=agent_completions - ) - response.raise_for_status() - return response.json() - except requests.exceptions.RequestException as e: - print(f"Error making batch request: {e}") - return None -``` - -#### Example Usage - -```python -batch_completions = [ - { - "agent_config": { - "agent_name": "Research Analyst", - "description": "An expert in analyzing research data", - "system_prompt": "You are a Research Analyst...", - "model_name": "gpt-4o", - "max_loops": 2 - }, - "task": "Analyze the impact of AI on healthcare delivery." - }, - { - "agent_config": { - "agent_name": "Market Analyst", - "description": "An expert in market analysis", - "system_prompt": "You are a Market Analyst...", - "model_name": "gpt-4o", - "max_loops": 1 - }, - "task": "Analyze the AI startup landscape in 2025." - } -] - -batch_results = run_batch_agents(batch_completions) -print(batch_results) -``` - -#### Response Structure - -```json -[ - { - "id": "agent-1a2b3c4d5e6f7g8h9i0j", - "success": true, - "name": "Research Analyst", - "description": "An expert in analyzing research data", - "temperature": 0.5, - "outputs": { - "content": "# Impact of AI on Healthcare Delivery\n...", - "role": "assistant" - }, - "usage": { - "input_tokens": 1250, - "output_tokens": 3822, - "total_tokens": 5072 - }, - "timestamp": "2025-05-10T18:35:29.421Z" - }, - { - "id": "agent-9i8h7g6f5e4d3c2b1a0", - "success": true, - "name": "Market Analyst", - "description": "An expert in market analysis", - "temperature": 0.5, - "outputs": { - "content": "# AI Startup Landscape 2025\n...", - "role": "assistant" - }, - "usage": { - "input_tokens": 980, - "output_tokens": 4120, - "total_tokens": 5100 - }, - "timestamp": "2025-05-10T18:35:31.842Z" - } -] -``` - -## Error Handling - -The API uses standard HTTP status codes to indicate success or failure: - -| Status Code | Meaning | -|-------------|---------| -| 200 | Success | -| 400 | Bad Request - Check your request parameters | -| 401 | Unauthorized - Invalid or missing API key | -| 403 | Forbidden - Insufficient permissions | -| 429 | Too Many Requests - Rate limit exceeded | -| 500 | Server Error - Something went wrong on the server | - -When an error occurs, the response body will contain additional information: - -```json -{ - "detail": "Error message explaining what went wrong" -} -``` - -### Common Errors and Solutions - -| Error | Possible Solution | -|-------|-------------------| -| "Invalid API Key" | Verify your API key is correct and properly included in the request headers | -| "Rate limit exceeded" | Reduce the number of requests or contact support to increase your rate limit | -| "Invalid agent configuration" | Check your agent_config parameters for any missing or invalid values | -| "Failed to create agent" | Ensure your system_prompt and model_name are valid | -| "Insufficient credits" | Add credits to your account at https://swarms.world/platform/account | - -## Advanced Usage - -### Setting Dynamic Temperature - -The agent can dynamically adjust its temperature for optimal outputs: - -```python -agent_config = { - # Other config options... - "temperature": 0.7, - "dynamic_temperature_enabled": True -} -``` - -### Using Agent Tools - -Agents can utilize various tools to enhance their capabilities: - -```python -agent_config = { - # Other config options... - "tools_dictionary": [ - { - "name": "web_search", - "description": "Search the web for information", - "parameters": { - "query": "string" - } - }, - { - "name": "calculator", - "description": "Perform mathematical calculations", - "parameters": { - "expression": "string" - } - } - ] -} -``` - -## Best Practices - -!!! tip "API Key Security" - Store API keys in environment variables or secure vaults, never in code repositories. - ```python - # DON'T do this - api_key = "sk-123456789abcdef" - - # DO this instead - import os - from dotenv import load_dotenv - load_dotenv() - api_key = os.getenv("SWARMS_API_KEY") - ``` - -!!! info "Agent Naming Conventions" - Use a consistent naming pattern for your agents to make your code more maintainable. - ```python - # Good naming convention - agent_configs = { - "market_analyst": {...}, - "research_specialist": {...}, - "code_reviewer": {...} - } - ``` - -!!! success "Crafting Effective System Prompts" - A well-crafted system prompt acts as your agent's personality and instruction set. - - === "Basic Prompt" - ``` - You are a research analyst. Analyze the data and provide insights. - ``` - - === "Enhanced Prompt" - ``` - You are a Research Analyst with 15+ years of experience in biotech market analysis. - - Your task is to: - 1. Analyze the provided market data methodically - 2. Identify key trends and emerging patterns - 3. Highlight potential investment opportunities - 4. Assess risks and regulatory considerations - 5. Provide actionable recommendations supported by the data - - Format your response as a professional report with clear sections, - focusing on data-driven insights rather than generalities. - ``` - -!!! warning "Token Management" - Manage your token usage carefully to control costs. - - - Higher token limits provide more complete responses but increase costs - - Consider using different models based on task complexity - - For gpt-4o models, typical settings: - - Simple tasks: 2048 tokens (lower cost) - - Medium complexity: 4096 tokens (balanced) - - Complex analysis: 8192+ tokens (higher cost, more detail) - -!!! danger "Error Handling" - Implement comprehensive error handling to make your application resilient. - - ```python - try: - response = requests.post( - f"{BASE_URL}/v1/agent/completions", - headers=headers, - json=payload, - timeout=30 # Add timeout to prevent hanging requests - ) - response.raise_for_status() - return response.json() - except requests.exceptions.HTTPError as e: - if e.response.status_code == 429: - # Implement exponential backoff for rate limiting - retry_after = int(e.response.headers.get('Retry-After', 5)) - time.sleep(retry_after) - return run_agent(payload) # Retry the request - elif e.response.status_code == 401: - logger.error("Authentication failed. Check your API key.") - else: - logger.error(f"HTTP Error: {e.response.status_code} - {e.response.text}") - return {"error": e.response.text} - except requests.exceptions.Timeout: - logger.error("Request timed out. The server might be busy.") - return {"error": "Request timed out"} - except requests.exceptions.RequestException as e: - logger.error(f"Request Error: {e}") - return {"error": str(e)} - ``` - -!!! example "Implementing Caching" - Cache identical requests to improve performance and reduce costs. - - ```python - import hashlib - import json - from functools import lru_cache - - def generate_cache_key(agent_config, task): - """Generate a unique cache key for an agent request.""" - cache_data = json.dumps({"agent_config": agent_config, "task": task}, sort_keys=True) - return hashlib.md5(cache_data.encode()).hexdigest() - - @lru_cache(maxsize=100) - def cached_agent_run(cache_key, agent_config, task): - """Run agent with caching based on config and task.""" - # Convert agent_config back to a dictionary if it's a string representation - if isinstance(agent_config, str): - agent_config = json.loads(agent_config) - - payload = { - "agent_config": agent_config, - "task": task - } - - try: - response = requests.post( - f"{BASE_URL}/v1/agent/completions", - headers=headers, - json=payload - ) - response.raise_for_status() - return response.json() - except Exception as e: - return {"error": str(e)} - - def run_agent_with_cache(agent_config, task): - """Wrapper function to run agent with caching.""" - # Generate a cache key - cache_key = generate_cache_key(agent_config, task) - - # Convert agent_config to a hashable type for lru_cache - hashable_config = json.dumps(agent_config, sort_keys=True) - - # Call the cached function - return cached_agent_run(cache_key, hashable_config, task) - ``` - -!!! abstract "Usage & Cost Monitoring" - Set up a monitoring system to track your API usage and costs. - - ```python - def log_api_usage(api_call_type, tokens_used, cost_estimate): - """Log API usage for monitoring.""" - with open("api_usage_log.csv", "a") as f: - timestamp = datetime.now().isoformat() - f.write(f"{timestamp},{api_call_type},{tokens_used},{cost_estimate}\n") - - def estimate_cost(tokens): - """Estimate cost based on token usage.""" - # Example pricing: $0.002 per 1K tokens (adjust according to current pricing) - return (tokens / 1000) * 0.002 - - def run_agent_with_logging(agent_config, task): - """Run agent and log usage.""" - result = run_single_agent(agent_config, task) - - if "usage" in result: - total_tokens = result["usage"]["total_tokens"] - cost = estimate_cost(total_tokens) - log_api_usage("single_agent", total_tokens, cost) - - return result - ``` - -## FAQ - -??? question "What's the difference between Single Agent and Batch Agent APIs?" - The Single Agent API (`/v1/agent/completions`) runs one agent with one task, while the Batch Agent API (`/v1/agent/batch/completions`) allows running multiple agents with different configurations and tasks in parallel. Use Batch Agent when you need to process multiple independent tasks efficiently. - -??? question "How do I choose the right model for my agent?" - Model selection depends on your task complexity, performance requirements, and budget: - - | Model | Best For | Characteristics | - |-------|----------|-----------------| - | gpt-4o | Complex analysis, creative tasks | Highest quality, most expensive | - | gpt-4o-mini | General purpose tasks | Good balance of quality and cost | - | openai/o3-mini | Simple, factual tasks | Fast, economical | - - For exploratory work, start with gpt-4o-mini and adjust based on results. - -??? question "What should I include in my system prompt?" - A good system prompt should include: - - 1. **Role definition**: Who the agent is and their expertise - 2. **Task instructions**: Specific, clear directions on what to do - 3. **Output format**: How results should be structured - 4. **Constraints**: Any limitations or requirements - 5. **Examples**: Sample inputs and outputs when helpful - - Keep prompts focused and avoid contradictory instructions. - -??? question "How can I optimize costs when using the Agent API?" - Cost optimization strategies include: - - - Use the appropriate model for your task complexity - - Set reasonable token limits based on expected output length - - Implement caching for repeated or similar requests - - Batch related requests together - - Use `max_loops: 1` unless you specifically need iterative refinement - - Monitor usage patterns and adjust configurations accordingly - -??? question "What's the maximum number of agents I can run in a batch?" - While there's no hard limit specified, we recommend keeping batch sizes under 20 agents for optimal performance. For very large batches, consider splitting them into multiple calls or contacting support for guidance on handling high-volume processing. - -??? question "How do I handle rate limiting?" - Implement exponential backoff in your error handling: - - ```python - import time - - def run_with_backoff(func, max_retries=5, initial_delay=1): - """Run a function with exponential backoff retry logic.""" - retries = 0 - delay = initial_delay - - while retries < max_retries: - try: - return func() - except requests.exceptions.HTTPError as e: - if e.response.status_code == 429: # Too Many Requests - retry_after = int(e.response.headers.get('Retry-After', delay)) - print(f"Rate limited. Retrying after {retry_after} seconds...") - time.sleep(retry_after) - retries += 1 - delay *= 2 # Exponential backoff - else: - raise - except Exception as e: - raise - - raise Exception(f"Failed after {max_retries} retries") - ``` - -??? question "Can I use tools with my agents?" - Yes, you can enable tools through the `tools_dictionary` parameter in your agent configuration. This allows agents to access external functionality like web searches, calculations, or custom tools. - - ```python - agent_config = { - # Other configuration... - "tools_dictionary": [ - { - "name": "web_search", - "description": "Search the web for current information", - "parameters": { - "query": { - "type": "string", - "description": "The search query" - } - } - } - ] - } - ``` - -??? question "How do I debug agent performance issues?" - Debugging steps for agent performance issues: - - 1. **Check system prompts**: Ensure they're clear and not overly restrictive - 2. **Review model selection**: Try a more capable model if output quality is poor - 3. **Adjust token limits**: Increase max_tokens if outputs are getting truncated - 4. **Examine temperature**: Lower for more deterministic outputs, higher for creativity - 5. **Test with simpler tasks**: Isolate whether the issue is with the task complexity - 6. **Enable verbose logging**: Add detailed logging to track request/response cycles - 7. **Contact support**: For persistent issues, reach out with example payloads and responses - -??? question "What's the pricing model for the Agent API?" - The Agent API uses a token-based pricing model: - - 1. **Input tokens**: Text sent to the API (task, system prompts) - 2. **Output tokens**: Text generated by the agent - - Pricing varies by model and is calculated per 1,000 tokens. Check the [pricing page](https://swarms.world/platform/pricing) for current rates. - - The API also offers a "flex" tier for lower-priority, cost-effective processing. - -## Further Resources - -[:material-file-document: Swarms.ai Documentation](https://docs.swarms.world){ .md-button } -[:material-application: Swarms.ai Platform](https://swarms.world/platform){ .md-button } -[:material-key: API Key Management](https://swarms.world/platform/api-keys){ .md-button } -[:material-forum: Swarms.ai Community](https://discord.gg/EamjgSaEQf){ .md-button } \ No newline at end of file diff --git a/docs/swarms_cloud/agent_rearrange.md b/docs/swarms_cloud/agent_rearrange.md deleted file mode 100644 index 73293d90..00000000 --- a/docs/swarms_cloud/agent_rearrange.md +++ /dev/null @@ -1,204 +0,0 @@ -# AgentRearrange - -*Dynamically reorganizes agents to optimize task performance and efficiency* - -**Swarm Type**: `AgentRearrange` - -## Overview - -The AgentRearrange swarm type dynamically reorganizes the workflow between agents based on task requirements and performance metrics. This architecture is particularly useful when the effectiveness of agents depends on their sequence or arrangement, allowing for optimal task distribution and execution flow. - -Key features: -- **Dynamic Reorganization**: Automatically adjusts agent order based on task needs -- **Performance Optimization**: Optimizes workflow for maximum efficiency -- **Adaptive Sequencing**: Learns from execution patterns to improve arrangement -- **Flexible Task Distribution**: Distributes work based on agent capabilities - -## Use Cases - -- Complex workflows where task order matters -- Multi-step processes requiring optimization -- Tasks where agent performance varies by sequence -- Adaptive workflow management systems - -## API Usage - -### Basic AgentRearrange Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Document Processing Rearrange", - "description": "Process documents with dynamic agent reorganization", - "swarm_type": "AgentRearrange", - "task": "Analyze this legal document and extract key insights, then summarize findings and identify action items", - "agents": [ - { - "agent_name": "Document Analyzer", - "description": "Analyzes document content and structure", - "system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Legal Expert", - "description": "Provides legal context and interpretation", - "system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Summarizer", - "description": "Creates concise summaries and action items", - "system_prompt": "You are an expert at creating clear, actionable summaries from complex information.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - } - ], - "rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer", - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Document Processing Rearrange", - "description": "Process documents with dynamic agent reorganization", - "swarm_type": "AgentRearrange", - "task": "Analyze this legal document and extract key insights, then summarize findings and identify action items", - "agents": [ - { - "agent_name": "Document Analyzer", - "description": "Analyzes document content and structure", - "system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Legal Expert", - "description": "Provides legal context and interpretation", - "system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Summarizer", - "description": "Creates concise summaries and action items", - "system_prompt": "You are an expert at creating clear, actionable summaries from complex information.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - } - ], - "rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer", - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("AgentRearrange swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Output: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-Uc8R7UcepLmNNPwcU7JC6YPy5wiI", - "status": "success", - "swarm_name": "Document Processing Rearrange", - "description": "Process documents with dynamic agent reorganization", - "swarm_type": "AgentRearrange", - "output": [ - { - "role": "Summarizer", - "content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\"" - }, - { - "role": "Legal Expert", - "content": "\"\"Absolutely! Please upload or describe the legal document you need assistance with, and I'll provide an analysis that highlights key insights, summarizes the findings, and identifies any action items that may be necessary.\"\"" - }, - { - "role": "Document Analyzer", - "content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\"" - } - ], - "number_of_agents": 3, - "service_tier": "standard", - "execution_time": 7.898931264877319, - "usage": { - "input_tokens": 22, - "output_tokens": 144, - "total_tokens": 166, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.03, - "input_token_cost": 0.000066, - "output_token_cost": 0.00216, - "token_counts": { - "total_input_tokens": 22, - "total_output_tokens": 144, - "total_tokens": 166 - }, - "num_agents": 3, - "service_tier": "standard", - "night_time_discount_applied": true - }, - "total_cost": 0.032226, - "discount_active": true, - "discount_type": "night_time", - "discount_percentage": 75 - } - } -} -``` - -## Configuration Options - -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `rearrange_flow` | string | Instructions for how agents should be rearranged | None | -| `agents` | Array | List of agents to be dynamically arranged | Required | -| `max_loops` | integer | Maximum rearrangement iterations | 1 | - -## Best Practices - -- Provide clear `rearrange_flow` instructions for optimal reorganization -- Design agents with complementary but flexible roles -- Use when task complexity requires adaptive sequencing -- Monitor execution patterns to understand rearrangement decisions - -## Related Swarm Types - -- [SequentialWorkflow](sequential_workflow.md) - For fixed sequential processing -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic swarm construction -- [HierarchicalSwarm](hierarchical_swarm.md) - For structured agent hierarchies \ No newline at end of file diff --git a/docs/swarms_cloud/api_clients.md b/docs/swarms_cloud/api_clients.md deleted file mode 100644 index ca41516a..00000000 --- a/docs/swarms_cloud/api_clients.md +++ /dev/null @@ -1,242 +0,0 @@ -# Swarms API Clients - -*Production-Ready Client Libraries for Every Programming Language* - -## Overview - -The Swarms API provides official client libraries across multiple programming languages, enabling developers to integrate powerful multi-agent AI capabilities into their applications with ease. Our clients are designed for production use, featuring robust error handling, comprehensive documentation, and seamless integration with existing codebases. - -Whether you're building enterprise applications, research prototypes, or innovative AI products, our client libraries provide the tools you need to harness the full power of the Swarms platform. - -## Available Clients - -| Language | Status | Repository | Documentation | Description | -|----------|--------|------------|---------------|-------------| -| **Python** | ✅ **Available** | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | Production-grade Python client with comprehensive error handling, retry logic, and extensive examples | -| **TypeScript/Node.js** | ✅ **Available** | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts) | 📚 *Coming Soon* | Modern TypeScript client with full type safety, Promise-based API, and Node.js compatibility | -| **Go** | ✅ **Available** | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | 📚 *Coming Soon* | High-performance Go client optimized for concurrent operations and microservices | -| **Java** | ✅ **Available** | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java) | 📚 *Coming Soon* | Enterprise Java client with Spring Boot integration and comprehensive SDK features | -| **Kotlin** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Modern Kotlin client with coroutines support and Android compatibility | -| **Ruby** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Elegant Ruby client with Rails integration and gem packaging | -| **Rust** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Ultra-fast Rust client with memory safety and zero-cost abstractions | -| **C#/.NET** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | .NET client with async/await support and NuGet packaging | - -## Client Features - -All Swarms API clients are built with the following enterprise-grade features: - -### 🔧 **Core Functionality** - -| Feature | Description | -|------------------------|--------------------------------------------------------------------| -| **Full API Coverage** | Complete access to all Swarms API endpoints | -| **Type Safety** | Strongly-typed interfaces for all request/response objects | -| **Error Handling** | Comprehensive error handling with detailed error messages | -| **Retry Logic** | Automatic retries with exponential backoff for transient failures | - ---- - -### 🚀 **Performance & Reliability** - -| Feature | Description | -|--------------------------|--------------------------------------------------------------------| -| **Connection Pooling** | Efficient HTTP connection management | -| **Rate Limiting** | Built-in rate limit handling and backoff strategies | -| **Timeout Configuration**| Configurable timeouts for different operation types | -| **Streaming Support** | Real-time streaming for long-running operations | - ---- - -### 🛡️ **Security & Authentication** - -| Feature | Description | -|------------------------|--------------------------------------------------------------------| -| **API Key Management** | Secure API key handling and rotation | -| **TLS/SSL** | End-to-end encryption for all communications | -| **Request Signing** | Optional request signing for enhanced security | -| **Environment Configuration** | Secure environment-based configuration | - ---- - -### 📊 **Monitoring & Debugging** - -| Feature | Description | -|----------------------------|--------------------------------------------------------------------| -| **Comprehensive Logging** | Detailed logging for debugging and monitoring | -| **Request/Response Tracing** | Full request/response tracing capabilities | -| **Metrics Integration** | Built-in metrics for monitoring client performance | -| **Debug Mode** | Enhanced debugging features for development | - - -## Client-Specific Features - -### Python Client - -| Feature | Description | -|------------------------|----------------------------------------------------------| -| **Async Support** | Full async/await support with `asyncio` | -| **Pydantic Integration** | Type-safe request/response models | -| **Context Managers** | Resource management with context managers | -| **Rich Logging** | Integration with Python's `logging` module | - ---- - -### TypeScript/Node.js Client - -| Feature | Description | -|------------------------|----------------------------------------------------------| -| **TypeScript First** | Built with TypeScript for maximum type safety | -| **Promise-Based** | Modern Promise-based API with async/await | -| **Browser Compatible** | Works in both Node.js and modern browsers | -| **Zero Dependencies** | Minimal dependency footprint | - ---- - -### Go Client - -| Feature | Description | -|------------------------|----------------------------------------------------------| -| **Context Support** | Full context.Context support for cancellation | -| **Structured Logging** | Integration with structured logging libraries | -| **Concurrency Safe** | Thread-safe design for concurrent operations | -| **Minimal Allocation** | Optimized for minimal memory allocation | - ---- - -### Java Client - -| Feature | Description | -|------------------------|----------------------------------------------------------| -| **Spring Boot Ready** | Built-in Spring Boot auto-configuration | -| **Reactive Support** | Optional reactive streams support | -| **Enterprise Features**| JMX metrics, health checks, and more | -| **Maven & Gradle** | Available on Maven Central | - -## Advanced Configuration - -### Environment Variables - -All clients support standard environment variables for configuration: - -```bash -# API Configuration -SWARMS_API_KEY=your_api_key_here -SWARMS_BASE_URL=https://api.swarms.world - -# Client Configuration -SWARMS_TIMEOUT=60 -SWARMS_MAX_RETRIES=3 -SWARMS_LOG_LEVEL=INFO -``` - -## Community & Support - -### 📚 **Documentation & Resources** - -| Resource | Link | -|-----------------------------|----------------------------------------------------------------------------------------| -| Complete API Documentation | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) | -| Python Client Docs | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | -| API Examples & Tutorials | [View Examples](https://docs.swarms.world/en/latest/examples/) | - ---- - -### 💬 **Community Support** - -| Community Channel | Description | Link | -|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| -| Discord Community | Join our active developer community for real-time support and discussions | [Join Discord](https://discord.gg/EamjgSaEQf) | -| GitHub Discussions | Ask questions and share ideas | [GitHub Discussions](https://github.com/The-Swarm-Corporation/swarms/discussions) | -| Twitter/X | Follow for updates and announcements | [Twitter/X](https://x.com/swarms_corp) | - ---- - -### 🐛 **Issue Reporting & Contributions** - -| Contribution Area | Description | Link | -|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| -| Report Bugs | Help us improve by reporting issues | [Report Bugs](https://github.com/The-Swarm-Corporation/swarms/issues) | -| Feature Requests | Suggest new features and improvements | [Feature Requests](https://github.com/The-Swarm-Corporation/swarms/issues) | -| Contributing Guide | Learn how to contribute to the project | [Contributing Guide](https://docs.swarms.world/en/latest/contributors/main/) | - ---- - -### 📧 **Direct Support** - -| Support Type | Contact Information | -|-----------------------------|---------------------------------------------------------------------------------------| -| Support Call | [Book a call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | -| Enterprise Support | Contact us for dedicated enterprise support options | - - -## Contributing to Client Development - -We welcome contributions to all our client libraries! Here's how you can help: - -### 🛠️ **Development** - -| Task | Description | -|-----------------------------------------|--------------------------------------------------| -| Implement new features and endpoints | Add new API features and expand client coverage | -| Improve error handling and retry logic | Enhance robustness and reliability | -| Add comprehensive test coverage | Ensure code quality and prevent regressions | -| Optimize performance and memory usage | Improve speed and reduce resource consumption | - ---- - -### 📝 **Documentation** - -| Task | Description | -|-----------------------------|-----------------------------------------------------| -| Write tutorials and examples | Create guides and sample code for users | -| Improve API documentation | Clarify and expand reference docs | -| Create integration guides | Help users connect clients to their applications | -| Translate documentation | Make docs accessible in multiple languages | - ---- - -### 🧪 **Testing** - -| Task | Description | -|-------------------------------|-----------------------------------------------------| -| Add unit and integration tests | Test individual components and end-to-end flows | -| Test with different language versions | Ensure compatibility across environments | -| Performance benchmarking | Measure and optimize speed and efficiency | -| Security testing | Identify and fix vulnerabilities | - ---- - -### 📦 **Packaging** - -| Task | Description | -|-------------------------------|-----------------------------------------------------| -| Package managers (npm, pip, Maven, etc.) | Publish to popular package repositories | -| Distribution optimization | Streamline builds and reduce package size | -| Version management | Maintain clear versioning and changelogs | -| Release automation | Automate build, test, and deployment pipelines | - -## Enterprise Features - -For enterprise customers, we offer additional features and support: - -### 🏢 **Enterprise Client Features** - -| Feature | Description | -|--------------------------|----------------------------------------------------------------| -| **Priority Support** | Dedicated support team with SLA guarantees | -| **Custom Integrations** | Tailored integrations for your specific needs | -| **On-Premises Deployment** | Support for on-premises or private cloud deployments | -| **Advanced Security** | Enhanced security features and compliance support | -| **Training & Onboarding**| Comprehensive training for your development team | - -### 📞 **Contact Enterprise Sales** - -| Contact Type | Details | -|----------------|-----------------------------------------------------------------------------------------| -| **Sales** | [kye@swarms.world](mailto:kye@swarms.world) | -| **Schedule Demo** | [Book a Demo](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) | -| **Partnership**| [kye@swarms.world](mailto:kye@swarms.world) | - ---- - -*Ready to build the future with AI agents? Start with any of our client libraries and join our growing community of developers building the next generation of intelligent applications.* \ No newline at end of file diff --git a/docs/swarms_cloud/api_pricing.md b/docs/swarms_cloud/api_pricing.md deleted file mode 100644 index 5f282c0d..00000000 --- a/docs/swarms_cloud/api_pricing.md +++ /dev/null @@ -1,198 +0,0 @@ -# Swarm Agent API Pricing - -!!! success "🎉 Get Started with $20 Free Credits!" - New users receive $20 in free credits when they sign up! [Create your account now](https://swarms.world/platform/account) to start building with our powerful multi-agent platform. - -!!! abstract "Overview" - The Swarm Agent API provides a powerful platform for managing multi-agent collaboration at scale and orchestrating swarms of LLM agents in the cloud. Our pricing model is designed to be transparent and cost-effective, enabling you to harness the full potential of your agents with ease. - -## Credit System - -The Swarm API operates on a credit-based system with the following characteristics: - -- **Credits** are the currency used within the platform - -- 1 credit = $1 USD - -- Credits can be purchased with USD or $swarms Solana tokens - -### Credit Types - -| Type | Description | Expiration | -|------|-------------|------------| -| Standard Credits | Purchased credits | Never expires | -| Free Credits | Promotional credits | May have expiration dates | - -## Pricing Structure - -### Base Costs - -| Cost Component | Price | -|----------------|-------| -| Base cost per agent | $0.01 per agent | - -### Token Usage Costs - -| Token Type | Cost | -|------------|------| -| Input tokens | $2.00 per 1M tokens | -| Output tokens | $4.50 per 1M tokens | - -### Night-Time Discount - -!!! tip "Off-Peak Hours Discount" - To encourage efficient resource usage during off-peak hours, we offer significant discounts for operations performed during California night-time hours: - - | Time Period (Pacific Time) | Discount | - |----------------------------|----------| - | 8:00 PM to 6:00 AM | 75% off token costs | - -## Cost Calculation - -### Formula - -The total cost for a swarm execution is calculated as follows: - -```math -Total Cost = (Number of Agents × $0.01) + - (Total Input Tokens / 1M × $2.00 × Number of Agents) + - (Total Output Tokens / 1M × $4.50 × Number of Agents) -``` - -With night-time discount applied: -```math -Input Token Cost = Input Token Cost × 0.25 -Output Token Cost = Output Token Cost × 0.25 -``` - -### Example Scenarios - -#### Scenario 1: Basic Workflow (Day-time) - -!!! example "Basic Workflow Example" - **Parameters:** - - - 3 agents - - - 10,000 input tokens total - - - 25,000 output tokens total - - **Calculation:** - - - Agent cost: 3 × $0.01 = $0.03 - - - Input token cost: (10,000 / 1,000,000) × $2.00 × 3 = $0.06 - - - Output token cost: (25,000 / 1,000,000) × $4.50 × 3 = $0.3375 - - - **Total cost: $0.4275** - -#### Scenario 2: Complex Workflow (Night-time) - -!!! example "Complex Workflow Example" - **Parameters:** - - - 5 agents - - - 50,000 input tokens total - - - 125,000 output tokens total - - **Calculation:** - - - Agent cost: 5 × $0.01 = $0.05 - - - Input token cost: (50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 - - - Output token cost: (125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 - - - **Total cost: $0.878125** - -## Purchasing Credits - -Credits can be purchased through our platform in two ways: - -### USD Payment - -- Available through our [account page](https://swarms.world/platform/account) - -- Secure payment processing - -- Minimum purchase: $10 - -### $swarms Token Payment - -- Use Solana-based $swarms tokens - -- Tokens can be purchased on supported exchanges - -- Connect your Solana wallet on our [account page](https://swarms.world/platform/account) - -## Free Credits - -!!! info "Free Credit Program" - We occasionally offer free credits to: - - - New users (welcome bonus) - - - During promotional periods - - - For educational and research purposes - - **Important Notes:** - - - Used before standard credits - - - May have expiration dates - - - May have usage restrictions - -## Billing and Usage Tracking - -Track your credit usage through our comprehensive logging and reporting features: - -### API Logs -- Access detailed logs via the `/v1/swarm/logs` endpoint - -- View cost breakdowns for each execution - -### Dashboard -- Real-time credit balance display - -- Historical usage graphs - -- Detailed cost analysis - -- Available at [https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard) - -## FAQ - -??? question "Is there a minimum credit purchase?" - Yes, the minimum credit purchase is $10 USD equivalent. - -??? question "Do credits expire?" - Standard credits do not expire. Free promotional credits may have expiration dates. - -??? question "How is the night-time discount applied?" - The system automatically detects the execution time based on Pacific Time (America/Los_Angeles) and applies a 75% discount to token costs for executions between 8:00 PM and 6:00 AM. - -??? question "What happens if I run out of credits during execution?" - Executions will fail with a 402 Payment Required error if sufficient credits are not available. We recommend maintaining a credit balance appropriate for your usage patterns. - -??? question "Can I get a refund for unused credits?" - Please contact our support team for refund requests for unused credits. - -??? question "Are there volume discounts available?" - Yes, please contact our sales team for enterprise pricing and volume discounts. - -## References - -- [Swarm API Documentation](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) -- [Account Management Portal](https://swarms.world/platform/account) -- [Swarm Types Reference](https://docs.swarms.world/swarms_cloud/swarm_types) - ---- - -!!! info "Need Help?" - For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world). \ No newline at end of file diff --git a/docs/swarms_cloud/auto.md b/docs/swarms_cloud/auto.md deleted file mode 100644 index e5e30df7..00000000 --- a/docs/swarms_cloud/auto.md +++ /dev/null @@ -1,55 +0,0 @@ -# Auto - -*Intelligently selects the most effective swarm architecture for a given task* - -**Swarm Type**: `auto` (or `Auto`) - -## Overview - -The Auto swarm type intelligently selects the most effective swarm architecture for a given task based on context analysis and task requirements. This intelligent system evaluates the task description and automatically chooses the optimal swarm type from all available architectures, ensuring maximum efficiency and effectiveness. - -Key features: -- **Intelligent Selection**: Automatically chooses the best swarm type for each task -- **Context Analysis**: Analyzes task requirements to make optimal decisions -- **Adaptive Architecture**: Adapts to different types of problems automatically -- **Zero Configuration**: No manual architecture selection required - -## Use Cases - -- When unsure about which swarm type to use -- General-purpose task automation -- Rapid prototyping and experimentation -- Simplified API usage for non-experts - -## API Usage - - - -## Selection Logic - -The Auto swarm type analyzes various factors to make its selection: - -| Factor | Consideration | -|--------|---------------| -| **Task Complexity** | Simple → Single agent, Complex → Multi-agent | -| **Sequential Dependencies** | Dependencies → SequentialWorkflow | -| **Parallel Opportunities** | Independent subtasks → ConcurrentWorkflow | -| **Collaboration Needs** | Discussion required → GroupChat | -| **Expertise Diversity** | Multiple domains → MixtureOfAgents | -| **Management Needs** | Oversight required → HierarchicalSwarm | -| **Routing Requirements** | Task distribution → MultiAgentRouter | - -## Best Practices - -- Provide detailed task descriptions for better selection -- Use `rules` parameter to guide selection criteria -- Review the selected architecture in response metadata -- Ideal for users new to swarm architectures - -## Related Swarm Types - -Since Auto can select any swarm type, it's related to all architectures: -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic agent generation -- [SequentialWorkflow](sequential_workflow.md) - Often selected for linear tasks -- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel processing needs -- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise requirements \ No newline at end of file diff --git a/docs/swarms_cloud/auto_swarm_builder.md b/docs/swarms_cloud/auto_swarm_builder.md deleted file mode 100644 index 895a6f77..00000000 --- a/docs/swarms_cloud/auto_swarm_builder.md +++ /dev/null @@ -1,46 +0,0 @@ -# AutoSwarmBuilder [ Needs an Fix ] - -*Automatically configures optimal swarm architectures based on task requirements* - -**Swarm Type**: `AutoSwarmBuilder` - -## Overview - -The AutoSwarmBuilder automatically configures optimal agent architectures based on task requirements and performance metrics, simplifying swarm creation. This intelligent system analyzes the given task and automatically generates the most suitable agent configuration, eliminating the need for manual swarm design. - -Key features: -- **Intelligent Configuration**: Automatically designs optimal swarm structures -- **Task-Adaptive**: Adapts architecture based on specific task requirements -- **Performance Optimization**: Selects configurations for maximum efficiency -- **Simplified Setup**: Eliminates manual agent configuration complexity - -## Use Cases - -- Quick prototyping and experimentation -- Unknown or complex task requirements -- Automated swarm optimization -- Simplified swarm creation for non-experts - -## API Usage - - -## Configuration Options - -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `task` | string | Task description for automatic optimization | Required | -| `rules` | string | Additional constraints and guidelines | None | -| `max_loops` | integer | Maximum execution rounds | 1 | - -## Best Practices - -- Provide detailed, specific task descriptions for better optimization -- Use `rules` parameter to guide the automatic configuration -- Ideal for rapid prototyping and experimentation -- Review generated architecture in response metadata - -## Related Swarm Types - -- [Auto](auto.md) - For automatic swarm type selection -- [MixtureOfAgents](mixture_of_agents.md) - Often selected by AutoSwarmBuilder -- [HierarchicalSwarm](hierarchical_swarm.md) - For complex structured tasks \ No newline at end of file diff --git a/docs/swarms_cloud/best_practices.md b/docs/swarms_cloud/best_practices.md deleted file mode 100644 index 76bb1e21..00000000 --- a/docs/swarms_cloud/best_practices.md +++ /dev/null @@ -1,170 +0,0 @@ -# Swarms API Best Practices Guide - -This comprehensive guide outlines production-grade best practices for using the Swarms API effectively. Learn how to choose the right swarm architecture, optimize costs, and implement robust error handling. - -## Quick Reference Cards - -=== "Swarm Types" - - !!! info "Available Swarm Architectures" - - | Swarm Type | Best For | Use Cases | - |------------|----------|------------| - | `AgentRearrange` | Dynamic workflows | - Complex task decomposition
- Adaptive processing
- Multi-stage analysis
- Dynamic resource allocation | - | `MixtureOfAgents` | Diverse expertise | - Cross-domain problems
- Comprehensive analysis
- Multi-perspective tasks
- Research synthesis | - | `SpreadSheetSwarm` | Data processing | - Financial analysis
- Data transformation
- Batch calculations
- Report generation | - | `SequentialWorkflow` | Linear processes | - Document processing
- Step-by-step analysis
- Quality control
- Content pipeline | - | `ConcurrentWorkflow` | Parallel tasks | - Batch processing
- Independent analyses
- High-throughput needs
- Multi-market analysis | - | `GroupChat` | Collaborative solving | - Brainstorming
- Decision making
- Problem solving
- Strategy development | - | `MultiAgentRouter` | Task distribution | - Load balancing
- Specialized processing
- Resource optimization
- Service routing | - | `AutoSwarmBuilder` | Automated setup | - Quick prototyping
- Simple tasks
- Testing
- MVP development | - | `HiearchicalSwarm` | Complex organization | - Project management
- Research analysis
- Enterprise workflows
- Team automation | - | `MajorityVoting` | Consensus needs | - Quality assurance
- Decision validation
- Risk assessment
- Content moderation | - -=== "Application Patterns" - - !!! tip "Specialized Application Configurations" - - | Application | Recommended Swarm | Benefits | - |------------|-------------------|-----------| - | **Team Automation** | `HiearchicalSwarm` | - Automated team coordination
- Clear responsibility chain
- Scalable team structure | - | **Research Pipeline** | `SequentialWorkflow` | - Structured research process
- Quality control at each stage
- Comprehensive output | - | **Trading System** | `ConcurrentWorkflow` | - Multi-market coverage
- Real-time analysis
- Risk distribution | - | **Content Factory** | `MixtureOfAgents` | - Automated content creation
- Consistent quality
- High throughput | - -=== "Cost Optimization" - - !!! tip "Advanced Cost Management Strategies" - - | Strategy | Implementation | Impact | - |----------|----------------|---------| - | Batch Processing | Group related tasks | 20-30% cost reduction | - | Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction | - | Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction | - | Caching | Store reusable results | 30-40% cost reduction | - | Agent Optimization | Use minimum required agents | 15-25% cost reduction | - | Smart Routing | Route to specialized agents | 10-15% cost reduction | - | Prompt Engineering | Optimize input tokens | 15-20% cost reduction | - | Flex Processing | Use flex tier for non-urgent tasks | 75% cost reduction | - -=== "Service Tiers" - - !!! tip "Choosing the Right Service Tier" - - | Tier | Best For | Benefits | Considerations | - |------|----------|----------|----------------| - | Standard | - Real-time processing
- Time-sensitive tasks
- Critical workflows | - Immediate execution
- Higher priority
- Predictable timing | - Higher cost
- 5-min timeout | - | Flex | - Batch processing
- Non-urgent tasks
- Cost-sensitive workloads | - 75% cost reduction
- Longer timeouts
- Auto-retries | - Variable timing
- Resource contention | - -=== "Industry Solutions" - - !!! example "Industry-Specific Swarm Patterns" - - | Industry | Use Case | Applications | - |----------|----------|--------------| - | **Finance** | Automated trading desk | - Portfolio management
- Risk assessment
- Market analysis
- Trading execution | - | **Healthcare** | Clinical workflow automation | - Patient analysis
- Diagnostic support
- Treatment planning
- Follow-up care | - | **Legal** | Legal document processing | - Document review
- Case analysis
- Contract review
- Compliance checks | - | **E-commerce** | E-commerce operations | - Product management
- Pricing optimization
- Customer support
- Inventory management | - -=== "Error Handling" - - !!! warning "Advanced Error Management Strategies" - - | Error Code | Strategy | Recovery Pattern | - |------------|----------|------------------| - | 400 | Input Validation | Pre-request validation with fallback | - | 401 | Auth Management | Secure key rotation and storage | - | 429 | Rate Limiting | Exponential backoff with queuing | - | 500 | Resilience | Retry with circuit breaking | - | 503 | High Availability | Multi-region redundancy | - | 504 | Timeout Handling | Adaptive timeouts with partial results | - -## Choosing the Right Swarm Architecture - -### Decision Framework - -Use this framework to select the optimal swarm architecture for your use case: - -1. **Task Complexity Analysis** - - Simple tasks → `AutoSwarmBuilder` - - Complex tasks → `HiearchicalSwarm` or `MultiAgentRouter` - - Dynamic tasks → `AgentRearrange` - -2. **Workflow Pattern** - - Linear processes → `SequentialWorkflow` - - Parallel operations → `ConcurrentWorkflow` - - Collaborative tasks → `GroupChat` - -3. **Domain Requirements** - - Multi-domain expertise → `MixtureOfAgents` - - Data processing → `SpreadSheetSwarm` - - Quality assurance → `MajorityVoting` - -### Industry-Specific Recommendations - -=== "Finance" - - !!! example "Financial Applications" - - Risk Analysis: `HiearchicalSwarm` - - Market Research: `MixtureOfAgents` - - Trading Strategies: `ConcurrentWorkflow` - - Portfolio Management: `SpreadSheetSwarm` - -=== "Healthcare" - - !!! example "Healthcare Applications" - - Patient Analysis: `SequentialWorkflow` - - Research Review: `MajorityVoting` - - Treatment Planning: `GroupChat` - - Medical Records: `MultiAgentRouter` - -=== "Legal" - - !!! example "Legal Applications" - - Document Review: `SequentialWorkflow` - - Case Analysis: `MixtureOfAgents` - - Compliance Check: `HiearchicalSwarm` - - Contract Analysis: `ConcurrentWorkflow` - -## Production Best Practices - -### Best Practices Summary - -!!! success "Recommended Patterns" - - Use appropriate swarm types for tasks - - Implement robust error handling - - Monitor and log executions - - Cache repeated results - - Rotate API keys regularly - - Choose appropriate service tier based on task urgency - - Use flex processing for batch and non-urgent tasks - -!!! danger "Anti-patterns to Avoid" - - Hardcoding API keys - - Ignoring rate limits - - Missing error handling - - Excessive agent count - - Inadequate monitoring - - Using standard tier for non-urgent tasks - - Not implementing retry logic for flex tier - -### Performance Benchmarks - -!!! note "Typical Performance Metrics" - - | Metric | Target Range | Warning Threshold | - |--------|--------------|-------------------| - | Response Time | < 2s (standard)
< 15s (flex) | > 5s (standard)
> 30s (flex) | - | Success Rate | > 99% | < 95% | - | Cost per Task | < $0.05 (standard)
< $0.0125 (flex) | > $0.10 (standard)
> $0.025 (flex) | - | Cache Hit Rate | > 80% | < 60% | - | Error Rate | < 1% | > 5% | - | Retry Rate (flex) | < 10% | > 30% | - -### Additional Resources - -!!! info "Useful Links" - - - [Swarms API Documentation](https://docs.swarms.world) - - [API Dashboard](https://swarms.world/platform/api-keys) \ No newline at end of file diff --git a/docs/swarms_cloud/chinese_api_pricing.md b/docs/swarms_cloud/chinese_api_pricing.md deleted file mode 100644 index ca935321..00000000 --- a/docs/swarms_cloud/chinese_api_pricing.md +++ /dev/null @@ -1,195 +0,0 @@ -# Swarm Agent API 定价文档 - - -Swarm Agent API 提供了一个强大的平台，用于大规模管理多代理协作和在云端编排 LLM 代理群。本文档概述了定价模型、成本计算方式以及如何购买和管理您的积分。 - -我们的定价设计旨在透明且具有成本效益，使您能够轻松发挥代理的全部潜力。成本基于： - -- 使用的代理数量 - -- 输入和输出令牌使用量 - -- 执行时间 - -## 积分系统 - -Swarm API 采用基于积分的系统： - -- **积分**是平台内使用的货币 - -- 1积分 = 1美元 - -- 积分可以用美元或 $swarms Solana 代币购买 - -- 两种类型的积分： - - - **标准积分**：购买的积分永不过期 - - - **免费积分**：促销积分，可能有使用限制 - -## 定价结构 - -### 基本成本 - -| 成本组成 | 价格 | -|----------------|-------| -| 每个代理的基本成本 | 每个代理$0.01 | - -### 令牌使用成本 - -| 令牌类型 | 成本 | -|------------|------| -| 输入令牌 | 每百万令牌$2.00 | -| 输出令牌 | 每百万令牌$4.50 | - -### 夜间折扣 - -为了鼓励在非高峰时段高效利用资源，我们在加州夜间时段提供显著折扣： - -| 时间段（太平洋时间） | 折扣 | -|----------------------------|----------| -| 晚上8:00至早上6:00 | 令牌成本75%折扣 | - -## 成本计算 - -### 公式 - -群体执行的总成本计算如下： - -``` -总成本 = (代理数量 × $0.01) + - (总输入令牌数 / 1M × $2.00 × 代理数量) + - (总输出令牌数 / 1M × $4.50 × 代理数量) -``` - -应用夜间折扣时： -``` -输入令牌成本 = 输入令牌成本 × 0.25 -输出令牌成本 = 输出令牌成本 × 0.25 -``` - -### 示例场景 - -#### 场景1：基本工作流（白天） - -- 3个代理 - -- 总共10,000个输入令牌 - -- 总共25,000个输出令牌 - -**计算：** - -- 代理成本：3 × $0.01 = $0.03 - -- 输入令牌成本：(10,000 / 1,000,000) × $2.00 × 3 = $0.06 - -- 输出令牌成本：(25,000 / 1,000,000) × $4.50 × 3 = $0.3375 - -- **总成本：$0.4275** - -#### 场景2：复杂工作流（夜间） - -- 5个代理 - -- 总共50,000个输入令牌 - -- 总共125,000个输出令牌 - -**计算：** - -- 代理成本：5 × $0.01 = $0.05 - -- 输入令牌成本：(50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125 - -- 输出令牌成本：(125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125 - -- **总成本：$0.878125** - -## 购买积分 - -可以通过我们的平台以两种方式购买积分： - -1. **美元支付** - - 可通过我们的[账户页面](https://swarms.world/platform/account)使用 - - 安全支付处理 - - 最低购买额：$10 - -2. **$swarms 代币支付** - - 使用基于Solana的$swarms代币 - - 可在支持的交易所购买代币 - - 在我们的[账户页面](https://swarms.world/platform/account)连接您的Solana钱包 - -## 免费积分 - -我们偶尔会向以下对象提供免费积分： - -- 新用户（欢迎奖励） - -- 促销期间 - -- 教育和研究目的 - -关于免费积分的说明： - -- 在标准积分之前使用 - -- 可能有过期日期 - -- 可能有使用限制 - -## 账单和使用跟踪 - -通过我们全面的日志和报告功能跟踪您的积分使用情况： - -1. **API日志** - - - 通过`/v1/swarm/logs`端点访问详细日志 - - - 查看每次执行的成本明细 - -2. **仪表板** - - - 实时积分余额显示 - - - 历史使用图表 - - - 详细成本分析 - - - 可在[https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)访问 - -## 常见问题 - -**问：是否有最低积分购买要求？** -答：是的，最低积分购买额为10美元等值。 - -**问：积分会过期吗？** -答：标准积分不会过期。免费促销积分可能有过期日期。 - -**问：夜间折扣如何应用？** -答：系统会根据太平洋时间（America/Los_Angeles）自动检测执行时间，并在晚上8:00至早上6:00之间的执行应用75%的令牌成本折扣。 - -**问：如果我在执行过程中积分用完了会怎样？** -答：如果没有足够的积分，执行将失败并显示402 Payment Required错误。我们建议维持适合您使用模式的积分余额。 - -**问：我可以获得未使用积分的退款吗？** -答：请联系我们的支持团队处理未使用积分的退款请求。 - -**问：是否有批量折扣？** -答：是的，请联系我们的销售团队了解企业定价和批量折扣。 - -## 参考资料 - -- [Swarm API 文档](https://docs.swarms.world) - -- [账户管理门户](https://swarms.world/platform/account) - -- [Swarm 类型参考](https://docs.swarms.world/swarm-types) - -- [令牌使用指南](https://docs.swarms.world/token-usage) - -- [API 参考](https://docs.swarms.world/api-reference) - ---- - -如有其他问题或自定义定价选项，请联系我们的支持团队，邮箱：kye@swarms.world \ No newline at end of file diff --git a/docs/swarms_cloud/concurrent_workflow.md b/docs/swarms_cloud/concurrent_workflow.md deleted file mode 100644 index aac81991..00000000 --- a/docs/swarms_cloud/concurrent_workflow.md +++ /dev/null @@ -1,214 +0,0 @@ -# ConcurrentWorkflow - -*Runs independent tasks in parallel for faster processing* - -**Swarm Type**: `ConcurrentWorkflow` - -## Overview - -The ConcurrentWorkflow swarm type runs independent tasks in parallel, significantly reducing processing time for complex operations. This architecture is ideal for tasks that can be processed simultaneously without dependencies, allowing multiple agents to work on different aspects of a problem at the same time. - -Key features: -- **Parallel Execution**: Multiple agents work simultaneously -- **Reduced Processing Time**: Faster completion through parallelization -- **Independent Tasks**: Agents work on separate, non-dependent subtasks -- **Scalable Performance**: Performance scales with the number of agents - -## Use Cases - -- Independent data analysis tasks -- Parallel content generation -- Multi-source research projects -- Distributed problem solving - -## API Usage - -### Basic ConcurrentWorkflow Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Market Research Concurrent", - "description": "Parallel market research across different sectors", - "swarm_type": "ConcurrentWorkflow", - "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors", - "agents": [ - { - "agent_name": "AI Market Analyst", - "description": "Analyzes AI market trends and opportunities", - "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Healthcare Market Analyst", - "description": "Analyzes healthcare market trends", - "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Fintech Market Analyst", - "description": "Analyzes fintech market opportunities", - "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "E-commerce Market Analyst", - "description": "Analyzes e-commerce market trends", - "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Market Research Concurrent", - "description": "Parallel market research across different sectors", - "swarm_type": "ConcurrentWorkflow", - "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors", - "agents": [ - { - "agent_name": "AI Market Analyst", - "description": "Analyzes AI market trends and opportunities", - "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Healthcare Market Analyst", - "description": "Analyzes healthcare market trends", - "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Fintech Market Analyst", - "description": "Analyzes fintech market opportunities", - "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "E-commerce Market Analyst", - "description": "Analyzes e-commerce market trends", - "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("ConcurrentWorkflow swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Parallel results: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-S17nZFDesmLHxCRoeyF3NVYvPaXk", - "status": "success", - "swarm_name": "Market Research Concurrent", - "description": "Parallel market research across different sectors", - "swarm_type": "ConcurrentWorkflow", - "output": [ - { - "role": "E-commerce Market Analyst", - "content": "To analyze market opportunities in the AI, healthcare, fintech, and e-commerce sectors, we can break down each sector's current trends, consumer behavior, and emerging platforms. Here's an overview of each sector with a focus on e-commerce....." - }, - { - "role": "AI Market Analyst", - "content": "The artificial intelligence (AI) landscape presents numerous opportunities across various sectors, particularly in healthcare, fintech, and e-commerce. Here's a detailed analysis of each sector:\n\n### Healthcare....." - }, - { - "role": "Healthcare Market Analyst", - "content": "As a Healthcare Market Analyst, I will focus on analyzing market opportunities within the healthcare sector, particularly in the realm of AI and digital health. The intersection of healthcare with fintech and e-commerce also presents unique opportunities. Here's an overview of key trends and growth areas:...." - }, - { - "role": "Fintech Market Analyst", - "content": "Certainly! Let's break down the market opportunities in the fintech sector, focusing on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments:\n\n### 1. Financial Technology Trends....." - } - ], - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 23.360230922698975, - "usage": { - "input_tokens": 35, - "output_tokens": 2787, - "total_tokens": 2822, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.000105, - "output_token_cost": 0.041805, - "token_counts": { - "total_input_tokens": 35, - "total_output_tokens": 2787, - "total_tokens": 2822 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": true - }, - "total_cost": 0.08191, - "discount_active": true, - "discount_type": "night_time", - "discount_percentage": 75 - } - } -} -``` - -## Best Practices - -- Design independent tasks that don't require sequential dependencies -- Use for tasks that can be parallelized effectively -- Ensure agents have distinct, non-overlapping responsibilities -- Ideal for time-sensitive analysis requiring multiple perspectives - -## Related Swarm Types - -- [SequentialWorkflow](sequential_workflow.md) - For ordered execution -- [MixtureOfAgents](mixture_of_agents.md) - For collaborative analysis -- [MultiAgentRouter](multi_agent_router.md) - For intelligent task distribution \ No newline at end of file diff --git a/docs/swarms_cloud/group_chat.md b/docs/swarms_cloud/group_chat.md deleted file mode 100644 index 3c3ee17c..00000000 --- a/docs/swarms_cloud/group_chat.md +++ /dev/null @@ -1,189 +0,0 @@ -# GroupChat - -*Enables dynamic collaboration through chat-based interaction* - -**Swarm Type**: `GroupChat` - -## Overview - -The GroupChat swarm type enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. Agents participate in a conversational workflow where they can build upon each other's contributions, debate ideas, and reach consensus through natural dialogue. - -Key features: -- **Interactive Dialogue**: Agents communicate through natural conversation -- **Dynamic Collaboration**: Real-time information sharing and building upon ideas -- **Consensus Building**: Agents can debate and reach decisions collectively -- **Flexible Participation**: Agents can contribute when relevant to the discussion - -## Use Cases - -- Brainstorming and ideation sessions -- Multi-perspective problem analysis -- Collaborative decision-making processes -- Creative content development - -## API Usage - -### Basic GroupChat Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Product Strategy Discussion", - "description": "Collaborative chat to develop product strategy", - "swarm_type": "GroupChat", - "task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses", - "agents": [ - { - "agent_name": "Product Manager", - "description": "Leads product strategy and development", - "system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "Marketing Strategist", - "description": "Develops marketing and positioning strategy", - "system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "Sales Director", - "description": "Provides sales and customer perspective", - "system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "UX Researcher", - "description": "Represents user experience and research insights", - "system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.", - "model_name": "gpt-4o", - "max_loops": 3, - } - ], - "max_loops": 3 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Product Strategy Discussion", - "description": "Collaborative chat to develop product strategy", - "swarm_type": "GroupChat", - "task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses", - "agents": [ - { - "agent_name": "Product Manager", - "description": "Leads product strategy and development", - "system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "Marketing Strategist", - "description": "Develops marketing and positioning strategy", - "system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "Sales Director", - "description": "Provides sales and customer perspective", - "system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.", - "model_name": "gpt-4o", - "max_loops": 3, - }, - { - "agent_name": "UX Researcher", - "description": "Represents user experience and research insights", - "system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.", - "model_name": "gpt-4o", - "max_loops": 3, - } - ], - "max_loops": 3 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("GroupChat swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Chat discussion: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-2COVtf3k0Fz7jU1BOOHF3b5nuL2x", - "status": "success", - "swarm_name": "Product Strategy Discussion", - "description": "Collaborative chat to develop product strategy", - "swarm_type": "GroupChat", - "output": "User: \n\nSystem: \n Group Chat Name: Product Strategy Discussion\nGroup Chat Description: Collaborative chat to develop product strategy\n Agents in your Group Chat: Available Agents for Team: None\n\n\n\n[Agent 1]\nName: Product Manager\nDescription: Leads product strategy and development\nRole.....", - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 47.36732482910156, - "usage": { - "input_tokens": 30, - "output_tokens": 1633, - "total_tokens": 1663, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.00009, - "output_token_cost": 0.024495, - "token_counts": { - "total_input_tokens": 30, - "total_output_tokens": 1633, - "total_tokens": 1663 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": false - }, - "total_cost": 0.064585, - "discount_active": false, - "discount_type": "none", - "discount_percentage": 0 - } - } -} -``` - -## Best Practices - -- Set clear discussion goals and objectives -- Use diverse agent personalities for richer dialogue -- Allow multiple conversation rounds for idea development -- Encourage agents to build upon each other's contributions - -## Related Swarm Types - -- [MixtureOfAgents](mixture_of_agents.md) - For complementary expertise -- [MajorityVoting](majority_voting.md) - For consensus decision-making -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic discussion setup \ No newline at end of file diff --git a/docs/swarms_cloud/hierarchical_swarm.md b/docs/swarms_cloud/hierarchical_swarm.md deleted file mode 100644 index 70c8792e..00000000 --- a/docs/swarms_cloud/hierarchical_swarm.md +++ /dev/null @@ -1,252 +0,0 @@ -# HiearchicalSwarm - -*Implements structured, multi-level task management with clear authority* - -**Swarm Type**: `HiearchicalSwarm` - -## Overview - -The HiearchicalSwarm implements a structured, multi-level approach to task management with clear lines of authority and delegation. This architecture organizes agents in a hierarchical structure where manager agents coordinate and oversee worker agents, enabling efficient task distribution and quality control. - -Key features: -- **Structured Hierarchy**: Clear organizational structure with managers and workers -- **Delegated Authority**: Manager agents distribute tasks to specialized workers -- **Quality Oversight**: Multi-level review and validation processes -- **Scalable Organization**: Efficient coordination of large agent teams - -## Use Cases - -- Complex projects requiring management oversight -- Large-scale content production workflows -- Multi-stage validation and review processes -- Enterprise-level task coordination - -## API Usage - -### Basic HiearchicalSwarm Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Market Research ", - "description": "Parallel market research across different sectors", - "swarm_type": "HiearchicalSwarm", - "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors", - "agents": [ - { - "agent_name": "AI Market Analyst", - "description": "Analyzes AI market trends and opportunities", - "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Healthcare Market Analyst", - "description": "Analyzes healthcare market trends", - "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Fintech Market Analyst", - "description": "Analyzes fintech market opportunities", - "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "E-commerce Market Analyst", - "description": "Analyzes e-commerce market trends", - "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Market Research ", - "description": "Parallel market research across different sectors", - "swarm_type": "HiearchicalSwarm", - "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors", - "agents": [ - { - "agent_name": "AI Market Analyst", - "description": "Analyzes AI market trends and opportunities", - "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Healthcare Market Analyst", - "description": "Analyzes healthcare market trends", - "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Fintech Market Analyst", - "description": "Analyzes fintech market opportunities", - "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "E-commerce Market Analyst", - "description": "Analyzes e-commerce market trends", - "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("HiearchicalSwarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Project plan: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-JIrcIAfs2d75xrXGaAL94uWyYJ8V", - "status": "success", - "swarm_name": "Market Research Auto", - "description": "Parallel market research across different sectors", - "swarm_type": "HiearchicalSwarm", - "output": [ - { - "role": "System", - "content": "These are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| AI Market Analyst | Analyzes AI market trends and opportunities |\n| Healthcare Market Analyst | Analyzes healthcare market trends |\n| Fintech Market Analyst | Analyzes fintech market opportunities |\n| E-commerce Market Analyst | Analyzes e-commerce market trends |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles." - }, - { - "role": "Director", - "content": [ - { - "role": "Director", - "content": [ - { - "function": { - "arguments": "{\"plan\":\"Conduct a comprehensive analysis of market opportunities in the AI, healthcare, fintech, and e-commerce sectors. Each market analyst will focus on their respective sector, gathering data on current trends, growth opportunities, and potential challenges. The findings will be compiled into a report for strategic decision-making.\",\"orders\":[{\"agent_name\":\"AI Market Analyst\",\"task\":\"Research current trends in the AI market, identify growth opportunities, and analyze potential challenges.\"},{\"agent_name\":\"Healthcare Market Analyst\",\"task\":\"Analyze the healthcare market for emerging trends, growth opportunities, and possible challenges.\"},{\"agent_name\":\"Fintech Market Analyst\",\"task\":\"Investigate the fintech sector for current trends, identify opportunities for growth, and assess challenges.\"},{\"agent_name\":\"E-commerce Market Analyst\",\"task\":\"Examine e-commerce market trends, identify growth opportunities, and analyze potential challenges.\"}]}", - "name": "ModelMetaclass" - }, - "id": "call_GxiyzIRb2oGQXokbbkeaeVry", - "type": "function" - } - ] - } - ] - }, - { - "role": "AI Market Analyst", - "content": "### AI Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the AI Market:\n\n1. **Increased Adoption Across Industries**..." - }, - { - "role": "Healthcare Market Analyst", - "content": "### Healthcare Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Healthcare Market:\n\n1. **Telehealth Expansion**..." - }, - { - "role": "Fintech Market Analyst", - "content": "### Fintech Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Fintech Market:\n\n1. **Digital Payments Proliferation**...." - }, - { - "role": "E-commerce Market Analyst", - "content": "### E-commerce Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the E-commerce Market:\n\n1. **Omnichannel Retailing**...." - }, - { - "role": "Director", - "content": "### Feedback for Worker Agents\n\n#### AI Market Analyst\n\n**Strengths:**\n- Comprehensive coverage of current trends, growth opportunities, and challenges in the AI market.\n- Clear categorization of insights, making it easy to follow and understand.\n\n**Weaknesses....." - }, - { - "role": "System", - "content": "--- Loop 1/1 completed ---" - } - ], - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 94.07934331893921, - "usage": { - "input_tokens": 35, - "output_tokens": 3827, - "total_tokens": 3862, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.000105, - "output_token_cost": 0.057405, - "token_counts": { - "total_input_tokens": 35, - "total_output_tokens": 3827, - "total_tokens": 3862 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": false - }, - "total_cost": 0.09751, - "discount_active": false, - "discount_type": "none", - "discount_percentage": 0 - } - } -} -``` - -## Configuration Options - -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `role` | string | Agent role: "manager" or "worker" | "worker" | -| `agents` | Array | Mix of manager and worker agents | Required | -| `max_loops` | integer | Coordination rounds for managers | 1 | - -## Best Practices - -- Clearly define manager and worker roles using the `role` parameter -- Give managers higher `max_loops` for coordination activities -- Design worker agents with specialized, focused responsibilities -- Use for complex projects requiring oversight and coordination - -## Related Swarm Types - -- [SequentialWorkflow](sequential_workflow.md) - For linear task progression -- [MultiAgentRouter](multi_agent_router.md) - For intelligent task routing -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic hierarchy creation \ No newline at end of file diff --git a/docs/swarms_cloud/index.md b/docs/swarms_cloud/index.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/swarms_cloud/launch.md b/docs/swarms_cloud/launch.md deleted file mode 100644 index 2d53e47f..00000000 --- a/docs/swarms_cloud/launch.md +++ /dev/null @@ -1,369 +0,0 @@ -# Swarms Cloud API Client Documentation - -## Overview -The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents. - -## Installation -```bash -pip install swarms-cloud -``` - -## Quick Start -```python -from swarms_cloud import SwarmCloudAPI, AgentCreate - -# Initialize the client -client = SwarmCloudAPI( - base_url="https://swarmcloud-285321057562.us-central1.run.app", - api_key="your_api_key_here" -) - -# Create an agent -agent_data = AgentCreate( - name="TranslateAgent", - description="Translates text between languages", - code=""" - def main(request, store): - text = request.payload.get('text', '') - return f'Translated: {text}' - """, - requirements="requests==2.25.1", - envs="DEBUG=True" -) - -new_agent = client.create_agent(agent_data) -print(f"Created agent with ID: {new_agent.id}") -``` - -## Client Configuration - -### Constructor Parameters - -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|----------|-------------| -| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API | -| api_key | str | Yes | None | Your SwarmCloud API key | -| timeout | float | No | 10.0 | Request timeout in seconds | - -## Data Models - -### AgentCreate -Model for creating new agents. - -| Field | Type | Required | Default | Description | -|-------|------|----------|----------|-------------| -| name | str | Yes | - | Name of the agent | -| description | str | No | None | Description of the agent's purpose | -| code | str | Yes | - | Python code that defines the agent's behavior | -| requirements | str | No | None | Python package requirements (pip format) | -| envs | str | No | None | Environment variables for the agent | -| autoscaling | bool | No | False | Enable/disable concurrent execution scaling | - -### AgentUpdate -Model for updating existing agents. - -| Field | Type | Required | Default | Description | -|-------|------|----------|----------|-------------| -| name | str | No | None | Updated name of the agent | -| description | str | No | None | Updated description | -| code | str | No | None | Updated Python code | -| requirements | str | No | None | Updated package requirements | -| autoscaling | bool | No | None | Updated autoscaling setting | - -## API Methods - -### List Agents -Retrieve all available agents. - -```python -agents = client.list_agents() -for agent in agents: - print(f"Agent: {agent.name} (ID: {agent.id})") -``` - -**Returns**: List[AgentOut] - -### Create Agent -Create a new agent with the specified configuration. - -```python -agent_data = AgentCreate( - name="DataProcessor", - description="Processes incoming data streams", - code=""" - def main(request, store): - data = request.payload.get('data', []) - return {'processed': len(data)} - """, - requirements="pandas==1.4.0\nnumpy==1.21.0", - envs="PROCESSING_MODE=fast", - autoscaling=True -) - -new_agent = client.create_agent(agent_data) -``` - -**Returns**: AgentOut - -### Get Agent -Retrieve details of a specific agent. - -```python -agent = client.get_agent("agent_id_here") -print(f"Agent details: {agent}") -``` - -**Parameters**: -- agent_id (str): The unique identifier of the agent - -**Returns**: AgentOut - -### Update Agent -Update an existing agent's configuration. - -```python -update_data = AgentUpdate( - name="UpdatedProcessor", - description="Enhanced data processing capabilities", - code="def main(request, store):\n return {'status': 'updated'}" -) - -updated_agent = client.update_agent("agent_id_here", update_data) -``` - -**Parameters**: -- agent_id (str): The unique identifier of the agent -- update (AgentUpdate): The update data - -**Returns**: AgentOut - -### Execute Agent -Manually execute an agent with optional payload data. - -```python -# Execute with payload -result = client.execute_agent( - "agent_id_here", - payload={"text": "Hello, World!"} -) - -# Execute without payload -result = client.execute_agent("agent_id_here") -``` - -**Parameters**: -- agent_id (str): The unique identifier of the agent -- payload (Optional[Dict[str, Any]]): Execution payload data - -**Returns**: Dict[str, Any] - -### Get Agent History -Retrieve the execution history and logs for an agent. - -```python -history = client.get_agent_history("agent_id_here") -for execution in history.executions: - print(f"[{execution.timestamp}] {execution.log}") -``` - -**Parameters**: -- agent_id (str): The unique identifier of the agent - -**Returns**: AgentExecutionHistory - -### Batch Execute Agents -Execute multiple agents simultaneously with the same payload. - -```python -# Get list of agents -agents = client.list_agents() - -# Execute batch with payload -results = client.batch_execute_agents( - agents=agents[:3], # Execute first three agents - payload={"data": "test"} -) - -print(f"Batch execution results: {results}") -``` - -**Parameters**: -- agents (List[AgentOut]): List of agents to execute -- payload (Optional[Dict[str, Any]]): Shared execution payload - -**Returns**: List[Any] - -### Health Check -Check the API's health status. - -```python -status = client.health() -print(f"API Status: {status}") -``` - -**Returns**: Dict[str, Any] - -## Error Handling -The client uses exception handling to manage various error scenarios: - -```python -from swarms_cloud import SwarmCloudAPI -import httpx - -try: - client = SwarmCloudAPI(api_key="your_api_key_here") - agents = client.list_agents() -except httpx.HTTPError as http_err: - print(f"HTTP error occurred: {http_err}") -except Exception as err: - print(f"An unexpected error occurred: {err}") -finally: - client.close() -``` - -## Context Manager Support -The client can be used with Python's context manager: - -```python -with SwarmCloudAPI(api_key="your_api_key_here") as client: - status = client.health() - print(f"API Status: {status}") - # Client automatically closes after the with block -``` - -## Best Practices - -1. Always close the client when finished: -```python -client = SwarmCloudAPI(api_key="your_api_key_here") -try: - # Your code here -finally: - client.close() -``` - -2. Use context managers for automatic cleanup: -```python -with SwarmCloudAPI(api_key="your_api_key_here") as client: - # Your code here -``` - -3. Handle errors appropriately: -```python -try: - result = client.execute_agent("agent_id", payload={"data": "test"}) -except httpx.HTTPError as e: - logger.error(f"HTTP error: {e}") - # Handle error appropriately -``` - -4. Set appropriate timeouts for your use case: -```python -client = SwarmCloudAPI( - api_key="your_api_key_here", - timeout=30.0 # Longer timeout for complex operations -) -``` - -## Complete Example -Here's a complete example showcasing various features of the client: - -```python -from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate -import httpx - -def main(): - with SwarmCloudAPI(api_key="your_api_key_here") as client: - # Create an agent - agent_data = AgentCreate( - name="DataAnalyzer", - description="Analyzes incoming data streams", - code=""" - def main(request, store): - data = request.payload.get('data', []) - return { - 'count': len(data), - 'summary': 'Data processed successfully' - } - """, - requirements="pandas==1.4.0", - autoscaling=True - ) - - try: - # Create the agent - new_agent = client.create_agent(agent_data) - print(f"Created agent: {new_agent.name} (ID: {new_agent.id})") - - # Execute the agent - result = client.execute_agent( - new_agent.id, - payload={"data": [1, 2, 3, 4, 5]} - ) - print(f"Execution result: {result}") - - # Update the agent - update_data = AgentUpdate( - description="Enhanced data analysis capabilities" - ) - updated_agent = client.update_agent(new_agent.id, update_data) - print(f"Updated agent: {updated_agent.name}") - - # Get execution history - history = client.get_agent_history(new_agent.id) - print(f"Execution history: {history}") - - except httpx.HTTPError as e: - print(f"HTTP error occurred: {e}") - except Exception as e: - print(f"Unexpected error: {e}") - -if __name__ == "__main__": - main() -``` - -## Logging -The client uses the `loguru` library for logging. You can configure the logging level and format: - -```python -from loguru import logger - -# Configure logging -logger.add("swarmcloud.log", rotation="500 MB") - -client = SwarmCloudAPI(api_key="your_api_key_here") -``` - -## Performance Considerations - -1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests. - -2. **Timeout Configuration**: Set appropriate timeouts based on your use case: -```python -client = SwarmCloudAPI( - api_key="your_api_key_here", - timeout=5.0 # Shorter timeout for time-sensitive operations -) -``` - -3. **Batch Operations**: Use batch_execute_agents for multiple agent executions: -```python -results = client.batch_execute_agents( - agents=agents, - payload=shared_payload -) -``` - -## Rate Limiting -The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed: - -```python -from tenacity import retry, stop_after_attempt, wait_exponential - -@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) -def execute_with_retry(client, agent_id, payload): - return client.execute_agent(agent_id, payload) -``` - -## Thread Safety -The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms. \ No newline at end of file diff --git a/docs/swarms_cloud/majority_voting.md b/docs/swarms_cloud/majority_voting.md deleted file mode 100644 index 5a95dfa0..00000000 --- a/docs/swarms_cloud/majority_voting.md +++ /dev/null @@ -1,249 +0,0 @@ -# MajorityVoting - -*Implements robust decision-making through consensus and voting* - -**Swarm Type**: `MajorityVoting` - -## Overview - -The MajorityVoting swarm type implements robust decision-making through consensus mechanisms, ideal for tasks requiring collective intelligence or verification. Multiple agents independently analyze the same problem and vote on the best solution, ensuring high-quality, well-validated outcomes through democratic consensus. - -Key features: -- **Consensus-Based Decisions**: Multiple agents vote on the best solution -- **Quality Assurance**: Reduces individual agent bias through collective input -- **Democratic Process**: Fair and transparent decision-making mechanism -- **Robust Validation**: Multiple perspectives ensure thorough analysis - -## Use Cases - -- Critical decision-making requiring validation -- Quality assurance and verification tasks -- Complex problem solving with multiple viable solutions -- Risk assessment and evaluation scenarios - -## API Usage - -### Basic MajorityVoting Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Investment Decision Voting", - "description": "Multiple financial experts vote on investment recommendations", - "swarm_type": "MajorityVoting", - "task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.", - "agents": [ - { - "agent_name": "Growth Investor", - "description": "Focuses on growth potential and market opportunity", - "system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Financial Analyst", - "description": "Analyzes financial metrics and projections", - "system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Technical Due Diligence", - "description": "Evaluates technology and product viability", - "system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Market Analyst", - "description": "Analyzes market conditions and competition", - "system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Risk Assessor", - "description": "Identifies and evaluates investment risks", - "system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Investment Decision Voting", - "description": "Multiple financial experts vote on investment recommendations", - "swarm_type": "MajorityVoting", - "task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.", - "agents": [ - { - "agent_name": "Growth Investor", - "description": "Focuses on growth potential and market opportunity", - "system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Financial Analyst", - "description": "Analyzes financial metrics and projections", - "system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Technical Due Diligence", - "description": "Evaluates technology and product viability", - "system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Market Analyst", - "description": "Analyzes market conditions and competition", - "system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Risk Assessor", - "description": "Identifies and evaluates investment risks", - "system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("MajorityVoting completed successfully!") - print(f"Final decision: {result['output']['consensus_decision']}") - print(f"Vote breakdown: {result['metadata']['vote_breakdown']}") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-1WFsSJU2KcvY11lxRMjdQNWFHArI", - "status": "success", - "swarm_name": "Investment Decision Voting", - "description": "Multiple financial experts vote on investment recommendations", - "swarm_type": "MajorityVoting", - "output": [ - { - "role": "Financial Analyst", - "content": [ - "To evaluate the potential investment in a renewable energy startup, we will assess the technology viability, intellectual property, product-market fit, and technical risks, along with the additional factors of market ....." - ] - }, - { - "role": "Technical Due Diligence", - "content": [ - "To evaluate the potential investment in a renewable energy startup, we will analyze the relevant market dynamics, competitive landscape, regulatory environment, and market timing. Here's the breakdown of the assessment......." - ] - }, - { - "role": "Market Analyst", - "content": [ - "To evaluate the potential investment in a renewable energy startup, let's break down the key factors:\n\n1. **Market Potential........" - ] - }, - { - "role": "Growth Investor", - "content": [ - "To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas: market potential, financial projections, team strength, and competitive landscape.\n\n### 1. Market Potential\n**Risks:**\n- **Regulatory Changes................" - ] - }, - { - "role": "Risk Assessor", - "content": [ - "To provide a comprehensive evaluation of whether to invest $1M in the renewable energy startup, let's break down the key areas.........." - ] - }, - { - "role": "Risk Assessor", - "content": "To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas....." - } - ], - "number_of_agents": 5, - "service_tier": "standard", - "execution_time": 61.74853563308716, - "usage": { - "input_tokens": 39, - "output_tokens": 8468, - "total_tokens": 8507, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.05, - "input_token_cost": 0.000117, - "output_token_cost": 0.12702, - "token_counts": { - "total_input_tokens": 39, - "total_output_tokens": 8468, - "total_tokens": 8507 - }, - "num_agents": 5, - "service_tier": "standard", - "night_time_discount_applied": false - }, - "total_cost": 0.177137, - "discount_active": false, - "discount_type": "none", - "discount_percentage": 0 - } - } -} -``` - -## Best Practices - -- Use odd numbers of agents to avoid tie votes -- Design agents with different perspectives for robust evaluation -- Include confidence scores in agent prompts for weighted decisions -- Ideal for high-stakes decisions requiring validation - -## Related Swarm Types - -- [GroupChat](group_chat.md) - For discussion-based consensus -- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise collaboration -- [HierarchicalSwarm](hierarchical_swarm.md) - For structured decision-making \ No newline at end of file diff --git a/docs/swarms_cloud/mcp.md b/docs/swarms_cloud/mcp.md deleted file mode 100644 index b0b3e6d2..00000000 --- a/docs/swarms_cloud/mcp.md +++ /dev/null @@ -1,342 +0,0 @@ -# Swarms API as MCP - -- Launch MCP server as a tool -- Put `SWARMS_API_KEY` in `.env` -- Client side code below - - -## Server Side - -```python -# server.py -from datetime import datetime -import os -from typing import Any, Dict, List, Optional - -import requests -import httpx -from fastmcp import FastMCP -from pydantic import BaseModel, Field -from swarms import SwarmType -from dotenv import load_dotenv - -load_dotenv() - -class AgentSpec(BaseModel): - agent_name: Optional[str] = Field( - description="The unique name assigned to the agent, which identifies its role and functionality within the swarm.", - ) - description: Optional[str] = Field( - description="A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.", - ) - system_prompt: Optional[str] = Field( - description="The initial instruction or context provided to the agent, guiding its behavior and responses during execution.", - ) - model_name: Optional[str] = Field( - default="gpt-4o-mini", - description="The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini", - ) - auto_generate_prompt: Optional[bool] = Field( - default=False, - description="A flag indicating whether the agent should automatically create prompts based on the task requirements.", - ) - max_tokens: Optional[int] = Field( - default=8192, - description="The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.", - ) - temperature: Optional[float] = Field( - default=0.5, - description="A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.", - ) - role: Optional[str] = Field( - default="worker", - description="The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.", - ) - max_loops: Optional[int] = Field( - default=1, - description="The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.", - ) - # New fields for RAG functionality - rag_collection: Optional[str] = Field( - None, - description="The Qdrant collection name for RAG functionality. If provided, this agent will perform RAG queries.", - ) - rag_documents: Optional[List[str]] = Field( - None, - description="Documents to ingest into the Qdrant collection for RAG. (List of text strings)", - ) - tools: Optional[List[Dict[str, Any]]] = Field( - None, - description="A dictionary of tools that the agent can use to complete its task.", - ) - - -class AgentCompletion(BaseModel): - """ - Configuration for a single agent that works together as a swarm to accomplish tasks. - """ - - agent: AgentSpec = Field( - ..., - description="The agent to run.", - ) - task: Optional[str] = Field( - ..., - description="The task to run.", - ) - img: Optional[str] = Field( - None, - description="An optional image URL that may be associated with the swarm's task or representation.", - ) - output_type: Optional[str] = Field( - "list", - description="The type of output to return.", - ) - - -class AgentCompletionResponse(BaseModel): - """ - Response from an agent completion. - """ - - agent_id: str = Field( - ..., - description="The unique identifier for the agent that completed the task.", - ) - agent_name: str = Field( - ..., - description="The name of the agent that completed the task.", - ) - agent_description: str = Field( - ..., - description="The description of the agent that completed the task.", - ) - messages: Any = Field( - ..., - description="The messages from the agent completion.", - ) - - cost: Dict[str, Any] = Field( - ..., - description="The cost of the agent completion.", - ) - - -class Agents(BaseModel): - """Configuration for a collection of agents that work together as a swarm to accomplish tasks.""" - - agents: List[AgentSpec] = Field( - description="A list containing the specifications of each agent that will participate in the swarm, detailing their roles and functionalities." - ) - - -class ScheduleSpec(BaseModel): - scheduled_time: datetime = Field( - ..., - description="The exact date and time (in UTC) when the swarm is scheduled to execute its tasks.", - ) - timezone: Optional[str] = Field( - "UTC", - description="The timezone in which the scheduled time is defined, allowing for proper scheduling across different regions.", - ) - - -class SwarmSpec(BaseModel): - name: Optional[str] = Field( - None, - description="The name of the swarm, which serves as an identifier for the group of agents and their collective task.", - max_length=100, - ) - description: Optional[str] = Field( - None, - description="A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.", - ) - agents: Optional[List[AgentSpec]] = Field( - None, - description="A list of agents or specifications that define the agents participating in the swarm.", - ) - max_loops: Optional[int] = Field( - default=1, - description="The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.", - ) - swarm_type: Optional[SwarmType] = Field( - None, - description="The classification of the swarm, indicating its operational style and methodology.", - ) - rearrange_flow: Optional[str] = Field( - None, - description="Instructions on how to rearrange the flow of tasks among agents, if applicable.", - ) - task: Optional[str] = Field( - None, - description="The specific task or objective that the swarm is designed to accomplish.", - ) - img: Optional[str] = Field( - None, - description="An optional image URL that may be associated with the swarm's task or representation.", - ) - return_history: Optional[bool] = Field( - True, - description="A flag indicating whether the swarm should return its execution history along with the final output.", - ) - rules: Optional[str] = Field( - None, - description="Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.", - ) - schedule: Optional[ScheduleSpec] = Field( - None, - description="Details regarding the scheduling of the swarm's execution, including timing and timezone information.", - ) - tasks: Optional[List[str]] = Field( - None, - description="A list of tasks that the swarm should complete.", - ) - messages: Optional[List[Dict[str, Any]]] = Field( - None, - description="A list of messages that the swarm should complete.", - ) - # rag_on: Optional[bool] = Field( - # None, - # description="A flag indicating whether the swarm should use RAG.", - # ) - # collection_name: Optional[str] = Field( - # None, - # description="The name of the collection to use for RAG.", - # ) - stream: Optional[bool] = Field( - False, - description="A flag indicating whether the swarm should stream its output.", - ) - - -class SwarmCompletionResponse(BaseModel): - """ - Response from a swarm completion. - """ - - status: str = Field(..., description="The status of the swarm completion.") - swarm_name: str = Field(..., description="The name of the swarm.") - description: str = Field(..., description="Description of the swarm.") - swarm_type: str = Field(..., description="The type of the swarm.") - task: str = Field( - ..., description="The task that the swarm is designed to accomplish." - ) - output: List[Dict[str, Any]] = Field( - ..., description="The output generated by the swarm." - ) - number_of_agents: int = Field( - ..., description="The number of agents involved in the swarm." - ) - # "input_config": Optional[Dict[str, Any]] = Field(None, description="The input configuration for the swarm.") - - -BASE_URL = "https://swarms-api-285321057562.us-east1.run.app" - - -# Create an MCP server -mcp = FastMCP("swarms-api") - - -# Add an addition tool -@mcp.tool(name="swarm_completion", description="Run a swarm completion.") -def swarm_completion(swarm: SwarmSpec) -> Dict[str, Any]: - api_key = os.getenv("SWARMS_API_KEY") - headers = {"x-api-key": api_key, "Content-Type": "application/json"} - - payload = swarm.model_dump() - - response = requests.post(f"{BASE_URL}/v1/swarm/completions", json=payload, headers=headers) - - return response.json() - -@mcp.tool(name="swarms_available", description="Get the list of available swarms.") -async def swarms_available() -> Any: - """ - Get the list of available swarms. - """ - headers = {"Content-Type": "application/json"} - - async with httpx.AsyncClient() as client: - response = await client.get(f"{BASE_URL}/v1/models/available", headers=headers) - response.raise_for_status() # Raise an error for bad responses - return response.json() - - -if __name__ == "__main__": - mcp.run(transport="sse") -``` - -## Client side - -- Call the tool with it's name and the payload config - -```python -import asyncio -from fastmcp import Client - -swarm_config = { - "name": "Simple Financial Analysis", - "description": "A swarm to analyze financial data", - "agents": [ - { - "agent_name": "Data Analyzer", - "description": "Looks at financial data", - "system_prompt": "Analyze the data.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - { - "agent_name": "Risk Analyst", - "description": "Checks risk levels", - "system_prompt": "Evaluate the risks.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - { - "agent_name": "Strategy Checker", - "description": "Validates strategies", - "system_prompt": "Review the strategy.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 1000, - "temperature": 0.5, - "auto_generate_prompt": False, - }, - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Analyze the financial data and provide insights.", - "return_history": False, # Added required field - "stream": False, # Added required field - "rules": None, # Added optional field - "img": None, # Added optional field -} - - -async def swarm_completion(): - """Connect to a server over SSE and fetch available swarms.""" - - async with Client( - transport="http://localhost:8000/sse" - ) as client: - # Basic connectivity testing - # print("Ping check:", await client.ping()) - # print("Available tools:", await client.list_tools()) - # print("Swarms available:", await client.call_tool("swarms_available", None)) - result = await client.call_tool("swarm_completion", {"swarm": swarm_config}) - print("Swarm completion:", result) - - -# Execute the function -if __name__ == "__main__": - asyncio.run(swarm_completion()) -``` \ No newline at end of file diff --git a/docs/swarms_cloud/mcs_api.md b/docs/swarms_cloud/mcs_api.md deleted file mode 100644 index 4a6ca6fe..00000000 --- a/docs/swarms_cloud/mcs_api.md +++ /dev/null @@ -1,727 +0,0 @@ -# Medical Coder Swarm API Documentation - -Base URL: `https://mcs-285321057562.us-central1.run.app` - -## Table of Contents -- [Authentication](#authentication) -- [Rate Limits](#rate-limits) -- [Endpoints](#endpoints) - - [Health Check](#health-check) - - [Run Medical Coder](#run-medical-coder) - - [Run Batch Medical Coder](#run-batch-medical-coder) - - [Get Patient Data](#get-patient-data) - - [Get All Patients](#get-all-patients) -- [Code Examples](#code-examples) -- [Error Handling](#error-handling) - -## Authentication - -Authentication details will be provided by the MCS team. Contact support for API credentials. - -## Rate Limits - -| Endpoint | GET Rate Limit Status | -|----------|----------------------| -| `GET /rate-limits` | Returns current rate limit status for your IP address | - -## Endpoints - -### Health Check - -Check if the API is operational. - -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/health` | Returns 200 OK if service is running | - -### Run Medical Coder - -Process a single patient case through the Medical Coder Swarm. - -| Method | Endpoint | Description | -|--------|----------|-------------| -| `POST` | `/v1/medical-coder/run` | Process a single patient case | - -**Request Body Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | string | Yes | Unique identifier for the patient | -| case_description | string | Yes | Medical case details to be processed | - -**Response Schema:** - -| Field | Type | Description | -|-------|------|-------------| -| patient_id | string | Patient identifier | -| case_data | string | Processed case data | - -### Run Batch Medical Coder - -Process multiple patient cases in a single request. - -| Method | Endpoint | Description | -|--------|----------|-------------| -| `POST` | `/v1/medical-coder/run-batch` | Process multiple patient cases | - -**Request Body Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| cases | array | Yes | Array of PatientCase objects | - -### Get Patient Data - -Retrieve data for a specific patient. - -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/v1/medical-coder/patient/{patient_id}` | Get patient data by ID | - -**Path Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | string | Yes | Patient identifier | - -### Get All Patients - -Retrieve data for all patients. - -| Method | Endpoint | Description | -|--------|----------|-------------| -| `GET` | `/v1/medical-coder/patients` | Get all patient data | - -## Code Examples - -### Python - -```python -import requests -import json - -class MCSClient: - def __init__(self, base_url="https://mcs.swarms.ai", api_key=None): - self.base_url = base_url - self.headers = { - "Content-Type": "application/json", - "Authorization": f"Bearer {api_key}" if api_key else None - } - - def run_medical_coder(self, patient_id, case_description): - endpoint = f"{self.base_url}/v1/medical-coder/run" - payload = { - "patient_id": patient_id, - "case_description": case_description - } - response = requests.post(endpoint, json=payload, headers=self.headers) - return response.json() - - def run_batch(self, cases): - endpoint = f"{self.base_url}/v1/medical-coder/run-batch" - payload = {"cases": cases} - response = requests.post(endpoint, json=payload, headers=self.headers) - return response.json() - -# Usage example -client = MCSClient(api_key="your_api_key") -result = client.run_medical_coder("P123", "Patient presents with...") -``` - -### Next.js (TypeScript) - -```typescript -// types.ts -interface PatientCase { - patient_id: string; - case_description: string; -} - -interface QueryResponse { - patient_id: string; - case_data: string; -} - -// api.ts -export class MCSApi { - private baseUrl: string; - private apiKey: string; - - constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') { - this.baseUrl = baseUrl; - this.apiKey = apiKey; - } - - private async fetchWithAuth(endpoint: string, options: RequestInit = {}) { - const response = await fetch(`${this.baseUrl}${endpoint}`, { - ...options, - headers: { - 'Content-Type': 'application/json', - 'Authorization': `Bearer ${this.apiKey}`, - ...options.headers, - }, - }); - return response.json(); - } - - async runMedicalCoder(patientCase: PatientCase): Promise { - return this.fetchWithAuth('/v1/medical-coder/run', { - method: 'POST', - body: JSON.stringify(patientCase), - }); - } - - async getPatientData(patientId: string): Promise { - return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`); - } -} - -// Usage in component -const mcsApi = new MCSApi(process.env.MCS_API_KEY); - -export async function ProcessPatientCase({ patientId, caseDescription }) { - const result = await mcsApi.runMedicalCoder({ - patient_id: patientId, - case_description: caseDescription, - }); - return result; -} -``` - -### Go - -```go -package mcs - -import ( - "bytes" - "encoding/json" - "fmt" - "net/http" -) - -type MCSClient struct { - BaseURL string - APIKey string - Client *http.Client -} - -type PatientCase struct { - PatientID string `json:"patient_id"` - CaseDescription string `json:"case_description"` -} - -type QueryResponse struct { - PatientID string `json:"patient_id"` - CaseData string `json:"case_data"` -} - -func NewMCSClient(apiKey string) *MCSClient { - return &MCSClient{ - BaseURL: "https://mcs.swarms.ai", - APIKey: apiKey, - Client: &http.Client{}, - } -} - -func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) { - payload, err := json.Marshal(patientCase) - if err != nil { - return nil, err - } - - req, err := http.NewRequest("POST", - fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL), - bytes.NewBuffer(payload)) - if err != nil { - return nil, err - } - - req.Header.Set("Content-Type", "application/json") - req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey)) - - resp, err := c.Client.Do(req) - if err != nil { - return nil, err - } - defer resp.Body.Close() - - var result QueryResponse - if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { - return nil, err - } - - return &result, nil -} - -// Usage example -func main() { - client := NewMCSClient("your_api_key") - - result, err := client.RunMedicalCoder(PatientCase{ - PatientID: "P123", - CaseDescription: "Patient presents with...", - }) - if err != nil { - panic(err) - } - - fmt.Printf("Result: %+v\n", result) -} -``` - - -## C Sharp - - -```txt -using System; -using System.Net.Http; -using System.Text; -using System.Text.Json; -using System.Threading.Tasks; - -namespace MedicalCoderSwarm -{ - public class PatientCase - { - public string PatientId { get; set; } - public string CaseDescription { get; set; } - } - - public class QueryResponse - { - public string PatientId { get; set; } - public string CaseData { get; set; } - } - - public class MCSClient : IDisposable - { - private readonly HttpClient _httpClient; - private readonly string _baseUrl; - - public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app") - { - _baseUrl = baseUrl; - _httpClient = new HttpClient(); - _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}"); - _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json"); - } - - public async Task RunMedicalCoderAsync(string patientId, string caseDescription) - { - var payload = new PatientCase - { - PatientId = patientId, - CaseDescription = caseDescription - }; - - var content = new StringContent( - JsonSerializer.Serialize(payload), - Encoding.UTF8, - "application/json" - ); - - var response = await _httpClient.PostAsync( - $"{_baseUrl}/v1/medical-coder/run", - content - ); - - response.EnsureSuccessStatusCode(); - - var responseContent = await response.Content.ReadAsStringAsync(); - return JsonSerializer.Deserialize(responseContent); - } - - public async Task GetPatientDataAsync(string patientId) - { - var response = await _httpClient.GetAsync( - $"{_baseUrl}/v1/medical-coder/patient/{patientId}" - ); - - response.EnsureSuccessStatusCode(); - - var responseContent = await response.Content.ReadAsStringAsync(); - return JsonSerializer.Deserialize(responseContent); - } - - public async Task HealthCheckAsync() - { - var response = await _httpClient.GetAsync($"{_baseUrl}/health"); - return response.IsSuccessStatusCode; - } - - public void Dispose() - { - _httpClient?.Dispose(); - } - } - - // Example usage - public class Program - { - public static async Task Main() - { - try - { - using var client = new MCSClient("your_api_key"); - - // Check API health - var isHealthy = await client.HealthCheckAsync(); - Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}"); - - // Process a single case - var result = await client.RunMedicalCoderAsync( - "P123", - "Patient presents with acute respiratory symptoms..." - ); - Console.WriteLine($"Processed case for patient {result.PatientId}"); - Console.WriteLine($"Case data: {result.CaseData}"); - - // Get patient data - var patientData = await client.GetPatientDataAsync("P123"); - Console.WriteLine($"Retrieved data for patient {patientData.PatientId}"); - } - catch (HttpRequestException ex) - { - Console.WriteLine($"API request failed: {ex.Message}"); - } - catch (Exception ex) - { - Console.WriteLine($"An error occurred: {ex.Message}"); - } - } - } -} - -``` - -## Error Handling - -The API uses standard HTTP status codes and returns detailed error messages in JSON format. - -**Common Status Codes:** - -| Status Code | Description | -|-------------|-------------| -| 200 | Success | -| 400 | Bad Request - Invalid input | -| 401 | Unauthorized - Invalid or missing API key | -| 422 | Validation Error - Request validation failed | -| 429 | Too Many Requests - Rate limit exceeded | -| 500 | Internal Server Error | - -**Error Response Format:** - -```json -{ - "detail": [ - { - "loc": ["body", "patient_id"], - "msg": "field required", - "type": "value_error.missing" - } - ] -} -``` - - -# MCS Python Client Documentation - -## Installation - -```bash -pip install mcs -``` - -## Quick Start - -```python -from mcs import MCSClient, PatientCase - -# Using context manager (recommended) -with MCSClient() as client: - # Process a single case - response = client.run_medical_coder( - patient_id="P123", - case_description="Patient presents with acute respiratory symptoms..." - ) - print(f"Processed case: {response.case_data}") - - # Process multiple cases - cases = [ - PatientCase("P124", "Case 1 description..."), - PatientCase("P125", "Case 2 description...") - ] - batch_response = client.run_batch(cases) -``` - -## Client Configuration - -### Constructor Arguments - -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| api_key | str | Yes | - | Authentication API key | -| base_url | str | No | "https://mcs.swarms.ai" | API base URL | -| timeout | int | No | 30 | Request timeout in seconds | -| max_retries | int | No | 3 | Maximum retry attempts | -| logger_name | str | No | "mcs" | Name for the logger instance | - -### Example Configuration - -```python -client = MCSClient( - base_url="https://custom-url.example.com", - timeout=45, - max_retries=5, - logger_name="custom_logger" -) -``` - -## Data Models - -### PatientCase - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| patient_id | str | Yes | Unique identifier for the patient | -| case_description | str | Yes | Medical case details | - -### QueryResponse - -| Field | Type | Description | -|-------|------|-------------| -| patient_id | str | Patient identifier | -| case_data | str | Processed case data | - -## Methods - -### run_medical_coder - -Process a single patient case. - -```python -def run_medical_coder( - self, - patient_id: str, - case_description: str -) -> QueryResponse: -``` - -**Arguments:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| patient_id | str | Yes | Patient identifier | -| case_description | str | Yes | Case details | - -**Example:** -```python -response = client.run_medical_coder( - patient_id="P123", - case_description="Patient presents with..." -) -print(response.case_data) -``` - -### run_batch - -Process multiple patient cases in batch. - -```python -def run_batch( - self, - cases: List[PatientCase] -) -> List[QueryResponse]: -``` - -**Arguments:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| cases | List[PatientCase] | Yes | List of patient cases | - -**Example:** -```python -cases = [ - PatientCase("P124", "Case 1 description..."), - PatientCase("P125", "Case 2 description...") -] -responses = client.run_batch(cases) -for response in responses: - print(f"Patient {response.patient_id}: {response.case_data}") -``` - -### get_patient_data - -Retrieve data for a specific patient. - -```python -def get_patient_data( - self, - patient_id: str -) -> QueryResponse: -``` - -**Example:** -```python -patient_data = client.get_patient_data("P123") -print(f"Patient data: {patient_data.case_data}") -``` - -### get_all_patients - -Retrieve data for all patients. - -```python -def get_all_patients(self) -> List[QueryResponse]: -``` - -**Example:** -```python -all_patients = client.get_all_patients() -for patient in all_patients: - print(f"Patient {patient.patient_id}: {patient.case_data}") -``` - -### get_rate_limits - -Get current rate limit status. - -```python -def get_rate_limits(self) -> Dict[str, Any]: -``` - -**Example:** -```python -rate_limits = client.get_rate_limits() -print(f"Rate limit status: {rate_limits}") -``` - -### health_check - -Check if the API is operational. - -```python -def health_check(self) -> bool: -``` - -**Example:** -```python -is_healthy = client.health_check() -print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}") -``` - -## Error Handling - -### Exception Hierarchy - -| Exception | Description | -|-----------|-------------| -| MCSClientError | Base exception for all client errors | -| RateLimitError | Raised when API rate limit is exceeded | -| AuthenticationError | Raised when API authentication fails | -| ValidationError | Raised when request validation fails | - -### Example Error Handling - -```python -from mcs import MCSClient, MCSClientError, RateLimitError - -with MCSClient() as client: - try: - response = client.run_medical_coder("P123", "Case description...") - except RateLimitError: - print("Rate limit exceeded. Please wait before retrying.") - except MCSClientError as e: - print(f"An error occurred: {str(e)}") -``` - -## Advanced Usage - -### Retry Configuration - -The client implements two levels of retry logic: - -1. Connection-level retries (using `HTTPAdapter`): -```python -client = MCSClient( - , - max_retries=5 # Adjusts connection-level retries -) -``` - -2. Application-level retries (using `tenacity`): -```python -from tenacity import retry, stop_after_attempt - -@retry(stop=stop_after_attempt(5)) -def process_with_custom_retries(): - with MCSClient() as client: - return client.run_medical_coder("P123", "Case description...") -``` - -### Batch Processing with Progress Tracking - -```python -from tqdm import tqdm - -with MCSClient() as client: - cases = [ - PatientCase(f"P{i}", f"Case description {i}") - for i in range(100) - ] - - # Process in smaller batches - batch_size = 10 - results = [] - - for i in tqdm(range(0, len(cases), batch_size)): - batch = cases[i:i + batch_size] - batch_results = client.run_batch(batch) - results.extend(batch_results) -``` - -## Best Practices - -1. **Always use context managers:** - ```python - with MCSClient() as client: - # Your code here - pass - ``` - -2. **Handle rate limits appropriately:** - ```python - from time import sleep - - def process_with_rate_limit_handling(): - with MCSClient() as client: - try: - return client.run_medical_coder("P123", "Case...") - except RateLimitError: - sleep(60) # Wait before retry - return client.run_medical_coder("P123", "Case...") - ``` - -3. **Implement proper logging:** - ```python - from loguru import logger - - logger.add("mcs.log", rotation="500 MB") - - with MCSClient() as client: - try: - response = client.run_medical_coder("P123", "Case...") - except Exception as e: - logger.exception(f"Error processing case: {str(e)}") - ``` - -4. **Monitor API health:** - ```python - def ensure_healthy_api(): - with MCSClient() as client: - if not client.health_check(): - raise SystemExit("API is not healthy") - ``` \ No newline at end of file diff --git a/docs/swarms_cloud/mixture_of_agents.md b/docs/swarms_cloud/mixture_of_agents.md deleted file mode 100644 index d90e225b..00000000 --- a/docs/swarms_cloud/mixture_of_agents.md +++ /dev/null @@ -1,222 +0,0 @@ -# MixtureOfAgents - -*Builds diverse teams of specialized agents for complex problem solving* - -**Swarm Type**: `MixtureOfAgents` - -## Overview - -The MixtureOfAgents swarm type combines multiple agent types with different specializations to tackle diverse aspects of complex problems. Each agent contributes unique skills and perspectives, making this architecture ideal for tasks requiring multiple types of expertise working in harmony. - -Key features: -- **Diverse Expertise**: Combines agents with different specializations -- **Collaborative Problem Solving**: Agents work together leveraging their unique strengths -- **Comprehensive Coverage**: Ensures all aspects of complex tasks are addressed -- **Balanced Perspectives**: Multiple viewpoints for robust decision-making - -## Use Cases - -- Complex research projects requiring multiple disciplines -- Business analysis needing various functional perspectives -- Content creation requiring different expertise areas -- Strategic planning with multiple considerations - -## API Usage - -### Basic MixtureOfAgents Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Business Strategy Mixture", - "description": "Diverse team analyzing business strategy from multiple perspectives", - "swarm_type": "MixtureOfAgents", - "task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector", - "agents": [ - { - "agent_name": "Market Research Analyst", - "description": "Analyzes market trends and opportunities", - "system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Financial Analyst", - "description": "Evaluates financial viability and projections", - "system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Regulatory Expert", - "description": "Analyzes compliance and regulatory requirements", - "system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.1 - }, - { - "agent_name": "Technology Strategist", - "description": "Evaluates technical feasibility and strategy", - "system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Business Strategy Mixture", - "description": "Diverse team analyzing business strategy from multiple perspectives", - "swarm_type": "MixtureOfAgents", - "task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector", - "agents": [ - { - "agent_name": "Market Research Analyst", - "description": "Analyzes market trends and opportunities", - "system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Financial Analyst", - "description": "Evaluates financial viability and projections", - "system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Regulatory Expert", - "description": "Analyzes compliance and regulatory requirements", - "system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.1 - }, - { - "agent_name": "Technology Strategist", - "description": "Evaluates technical feasibility and strategy", - "system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("MixtureOfAgents swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Output: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-kBZaJg1uGTkRbLCAsGztL2jrp5Mj", - "status": "success", - "swarm_name": "Business Strategy Mixture", - "description": "Diverse team analyzing business strategy from multiple perspectives", - "swarm_type": "MixtureOfAgents", - "output": [ - { - "role": "System", - "content": "Team Name: Business Strategy Mixture\nTeam Description: Diverse team analyzing business strategy from multiple perspectives\nThese are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| Market Research Analyst | Analyzes market trends and opportunities |\n| Financial Analyst | Evaluates financial viability and projections |\n| Regulatory Expert | Analyzes compliance and regulatory requirements |\n| Technology Strategist | Evaluates technical feasibility and strategy |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles." - }, - { - "role": "Market Research Analyst", - "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we will leverage the expertise of each team member to cover all critical aspects of the strategy. Here's how each agent will contribute......." - }, - { - "role": "Technology Strategist", - "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we'll need to collaborate effectively with the team, leveraging each member's expertise. Here's how each agent can contribute to the strategy, along with a focus on the technical requirements, implementation challenges, and scalability from the technology strategist's perspective....." - }, - { - "role": "Financial Analyst", - "content": "Developing a comprehensive market entry strategy for a new AI product in the healthcare sector involves a multidisciplinary approach. Each agent in the Business Strategy Mixture team will play a crucial role in ensuring a successful market entry. Here's how the team can collaborate........" - }, - { - "role": "Regulatory Expert", - "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we need to leverage the expertise of each agent in the Business Strategy Mixture team. Below is an outline of how each team member can contribute to this strategy......" - }, - { - "role": "Aggregator Agent", - "content": "As the Aggregator Agent, I've observed and analyzed the responses from the Business Strategy Mixture team regarding the development of a comprehensive market entry strategy for a new AI product in the healthcare sector. Here's a summary of the key points ......" - } - ], - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 30.230480670928955, - "usage": { - "input_tokens": 30, - "output_tokens": 3401, - "total_tokens": 3431, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.00009, - "output_token_cost": 0.051015, - "token_counts": { - "total_input_tokens": 30, - "total_output_tokens": 3401, - "total_tokens": 3431 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": true - }, - "total_cost": 0.091105, - "discount_active": true, - "discount_type": "night_time", - "discount_percentage": 75 - } - } -} -``` - -## Best Practices - -- Select agents with complementary and diverse expertise -- Ensure each agent has a clear, specialized role -- Use for complex problems requiring multiple perspectives -- Design tasks that benefit from collaborative analysis - -## Related Swarm Types - -- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task execution -- [GroupChat](group_chat.md) - For collaborative discussion -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic team assembly \ No newline at end of file diff --git a/docs/swarms_cloud/multi_agent_router.md b/docs/swarms_cloud/multi_agent_router.md deleted file mode 100644 index b69641a1..00000000 --- a/docs/swarms_cloud/multi_agent_router.md +++ /dev/null @@ -1,211 +0,0 @@ -# MultiAgentRouter - -*Intelligent task dispatcher distributing work based on agent capabilities* - -**Swarm Type**: `MultiAgentRouter` - -## Overview - -The MultiAgentRouter acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. This architecture analyzes incoming tasks and automatically routes them to the most suitable agents, optimizing both efficiency and quality of outcomes. - -Key features: -- **Intelligent Routing**: Automatically assigns tasks to best-suited agents -- **Capability Matching**: Matches task requirements with agent specializations -- **Load Balancing**: Distributes workload efficiently across available agents -- **Dynamic Assignment**: Adapts routing based on agent performance and availability - -## Use Cases - -- Customer service request routing -- Content categorization and processing -- Technical support ticket assignment -- Multi-domain question answering - -## API Usage - -### Basic MultiAgentRouter Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Customer Support Router", - "description": "Route customer inquiries to specialized support agents", - "swarm_type": "MultiAgentRouter", - "task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question", - "agents": [ - { - "agent_name": "Billing Specialist", - "description": "Handles billing, payments, and account issues", - "system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Technical Support", - "description": "Resolves technical issues and troubleshooting", - "system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Sales Consultant", - "description": "Provides product recommendations and sales support", - "system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - }, - { - "agent_name": "Policy Advisor", - "description": "Explains company policies and procedures", - "system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.1 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Customer Support Router", - "description": "Route customer inquiries to specialized support agents", - "swarm_type": "MultiAgentRouter", - "task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question", - "agents": [ - { - "agent_name": "Billing Specialist", - "description": "Handles billing, payments, and account issues", - "system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Technical Support", - "description": "Resolves technical issues and troubleshooting", - "system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - }, - { - "agent_name": "Sales Consultant", - "description": "Provides product recommendations and sales support", - "system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - }, - { - "agent_name": "Policy Advisor", - "description": "Explains company policies and procedures", - "system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.1 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("MultiAgentRouter completed successfully!") - print(f"Routing decisions: {result['metadata']['routing_decisions']}") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Customer responses: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-OvOZHubprE3thzLmRdNBZAxA6om4", - "status": "success", - "swarm_name": "Customer Support Router", - "description": "Route customer inquiries to specialized support agents", - "swarm_type": "MultiAgentRouter", - "output": [ - { - "role": "user", - "content": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question" - }, - { - "role": "Agent Router", - "content": "selected_agent='Billing Specialist' reasoning='The task involves multiple inquiries, but the first one is about a billing question regarding an overcharge. Billing issues often require immediate attention to ensure customer satisfaction and prevent further complications. Therefore, the Billing Specialist is the most appropriate agent to handle this task. They can address the billing question directly and potentially coordinate with other agents for the remaining inquiries.' modified_task='Billing question about overcharge'" - }, - { - "role": "Billing Specialist", - "content": "Of course, I'd be happy to help you with your billing question regarding an overcharge. Could you please provide me with more details about the charge in question, such as the date it occurred and the amount? This information will help me look into your account and resolve the issue as quickly as possible." - } - ], - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 7.800086975097656, - "usage": { - "input_tokens": 28, - "output_tokens": 221, - "total_tokens": 249, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.000084, - "output_token_cost": 0.003315, - "token_counts": { - "total_input_tokens": 28, - "total_output_tokens": 221, - "total_tokens": 249 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": true - }, - "total_cost": 0.043399, - "discount_active": true, - "discount_type": "night_time", - "discount_percentage": 75 - } - } -} -``` - -## Best Practices - -- Define agents with clear, distinct specializations -- Use descriptive agent names and descriptions for better routing -- Ideal for handling diverse task types that require different expertise -- Monitor routing decisions to optimize agent configurations - -## Related Swarm Types - -- [HierarchicalSwarm](hierarchical_swarm.md) - For structured task management -- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task processing -- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic routing setup \ No newline at end of file diff --git a/docs/swarms_cloud/production_deployment.md b/docs/swarms_cloud/production_deployment.md deleted file mode 100644 index 749e0530..00000000 --- a/docs/swarms_cloud/production_deployment.md +++ /dev/null @@ -1,319 +0,0 @@ -# Enterprise Guide to High-Performance Multi-Agent LLM Deployments -------- - -As large language models (LLMs) continue to advance and enable a wide range of powerful applications, enterprises are increasingly exploring multi-agent architectures to leverage the collective capabilities of multiple LLMs. However, coordinating and optimizing the performance of these complex multi-agent systems presents significant challenges. - -This comprehensive guide provides enterprise architects, engineering leaders, and technical decision-makers with a strategic framework for maximizing performance across multi-agent LLM deployments. Developed through extensive research and collaboration with industry partners, this guide distills best practices, proven techniques, and cutting-edge methodologies into seven core principles. - -By implementing the recommendations outlined in this guide, organizations can achieve superior latency, throughput, and resource utilization while ensuring scalability, cost-effectiveness, and optimal user experiences. Whether powering customer-facing conversational agents, driving internal knowledge management systems, or fueling mission-critical decision support tools, high-performance multi-agent LLM deployments will be pivotal to unlocking the full potential of this transformative technology. - -## Introduction - -The rise of large language models (LLMs) has ushered in a new era of human-machine interaction, enabling enterprises to develop sophisticated natural language processing (NLP) applications that can understand, generate, and reason with human-like text. However, as the complexity and scale of LLM deployments grow, traditional monolithic architectures are increasingly challenged to meet the stringent performance, scalability, and cost requirements of enterprise environments. - -Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLMs, have emerged as a powerful paradigm for addressing these challenges. By distributing workloads across a cohort of agents, each optimized for specific tasks or domains, multi-agent systems can deliver superior performance, resilience, and adaptability compared to single-model solutions. - -However, realizing the full potential of multi-agent LLM deployments requires a strategic approach to system design, optimization, and ongoing management. This guide presents a comprehensive framework for maximizing performance across seven core principles, each underpinned by a range of proven techniques and methodologies. - -Whether you are architecting a customer-facing conversational agent, building an internal knowledge management platform, or developing a mission-critical decision support system, this guide will equip you with the insights and best practices necessary to unlock the full potential of multi-agent LLM deployments within your enterprise. - -## Principle 1: Distribute Token Processing ----------------------------------------- - -At the heart of every LLM deployment lies the fundamental challenge of optimizing token processing -- the rate at which the model consumes and generates text inputs and outputs. In multi-agent architectures, distributing and parallelizing token processing across multiple agents is a critical performance optimization strategy. - -### Agent Specialization - -One of the key advantages of multi-agent architectures is the ability to dedicate specific agents to specialized tasks or domains. By carefully matching agents to the workloads they are optimized for, enterprises can maximize overall throughput and minimize latency. - -For example, in a conversational agent deployment, one agent may be optimized for intent recognition and query understanding, while another is fine-tuned for generating coherent, context-aware responses. In a document processing pipeline, separate agents could be dedicated to tasks such as named entity recognition, sentiment analysis, and summarization. - -To effectively leverage agent specialization, enterprises should: - -- Conduct a thorough analysis of their application's workflow and identify distinct tasks or domains that could benefit from dedicated agents. -- Evaluate the strengths and weaknesses of available LLM models and agents, and map them to the identified tasks or domains based on their capabilities and performance characteristics. -- Implement continuous monitoring and performance tuning processes to ensure agents remain optimized for their assigned workloads as models evolve and domain requirements shift. - -### Load Balancing - -Even with a well-designed allocation of tasks across specialized agents, fluctuations in workload and demand can create bottlenecks and performance degradation. Effective load balancing strategies are essential to ensure that token processing capacity is dynamically distributed across available agents based on real-time conditions. - -Load balancing in multi-agent LLM deployments can be accomplished through a combination of techniques, including: - -- **Round-Robin**: Distributing incoming requests across agents in a cyclical fashion, ensuring an even distribution of workload. -- **Least Connections**: Routing requests to the agent with the fewest active connections or outstanding tasks, minimizing the risk of overloading any single agent. -- **Response Time Monitoring**: Continuously monitoring the response times of each agent and dynamically adjusting request routing to favor faster-responding agents. -- **Resource-Based Routing**: Factoring in agent-level resource consumption (e.g., CPU, memory) when making routing decisions, ensuring that overloaded agents are relieved of additional workload. - -Implementing effective load balancing requires careful consideration of the specific characteristics and requirements of your multi-agent deployment, as well as the integration of robust monitoring and analytics capabilities to inform dynamic routing decisions. - -### Horizontal Scaling - -While load balancing optimizes the utilization of existing agent resources, horizontal scaling strategies enable organizations to dynamically provision additional token processing capacity to meet demand spikes or handle larger overall workloads. - -In multi-agent LLM deployments, horizontal scaling can be achieved through: - -- **Agent Replication**: Spin up additional instances of existing agents to increase parallel processing capacity for specific tasks or domains. -- **Hybrid Scaling**: Combine agent replication with the dynamic provisioning of additional compute resources (e.g., CPU, GPU) to support the increased agent count. -- **Serverless Deployment**: Leverage serverless computing platforms (e.g., AWS Lambda, Google Cloud Functions) to automatically scale agent instances based on real-time demand, minimizing idle resource consumption. - -Effective horizontal scaling requires robust orchestration and management capabilities, as well as seamless integration with load balancing mechanisms to ensure that incoming workloads are efficiently distributed across the dynamically scaled agent pool. - -## Principle 2: Optimize Agent Communication ------------------------------------------ - -In multi-agent LLM deployments, efficient inter-agent communication is crucial for coordinating tasks, exchanging context and intermediate results, and maintaining overall system coherence. However, communication overhead can quickly become a performance bottleneck if not carefully managed. - -### Minimizing Overhead - -Reducing the volume and complexity of information exchanged between agents is a key strategy for optimizing communication performance. Techniques for minimizing overhead include: - -- **Data Compression**: Applying lossless or lossy compression algorithms to reduce the size of data payloads exchanged between agents, lowering bandwidth requirements and transmission latencies. -- **Information Summarization**: Distilling and summarizing context, results, or other data exchanged between agents to its essential elements, minimizing redundant or non-critical information. -- **Differential Updates**: Rather than transmitting entire data payloads, agents can exchange only the differential updates or deltas required to synchronize their respective states. - -Implementing these techniques requires careful analysis of the specific data exchange patterns and communication requirements within your multi-agent deployment, as well as the integration of appropriate compression, summarization, and differential update algorithms. - -### Prioritizing Critical Information - -In scenarios where communication bandwidth or latency constraints cannot be fully alleviated through overhead reduction techniques, enterprises can prioritize the exchange of critical information over non-essential data. - -This can be achieved through: - -- **Prioritized Queuing**: Implementing queuing mechanisms that prioritize the transmission of high-priority, time-sensitive data over lower-priority, non-critical information. -- **Selective Communication**: Dynamically determining which agents require specific pieces of information based on their roles and responsibilities, and selectively transmitting data only to those agents that truly need it. -- **Progressive Information Exchange**: Exchanging information in a progressive or staged manner, with critical elements transmitted first, followed by supplementary or contextual data as bandwidth becomes available. - -Effective prioritization requires a deep understanding of the interdependencies and information flow within your multi-agent system, as well as the ability to dynamically assess and prioritize data based on its criticality and urgency. - -### Caching and Reusing Context - -In many multi-agent LLM deployments, agents frequently exchange or operate on shared context, such as user profiles, conversation histories, or domain-specific knowledge bases. Caching and reusing this context information can significantly reduce redundant communication and processing overhead. - -Strategies for optimizing context caching and reuse include: - -- **Agent-Level Caching**: Implementing caching mechanisms within individual agents to store and retrieve frequently accessed context data, minimizing the need for inter-agent communication. -- **Centralized Context Management**: Deploying a dedicated context management service or data store that agents can query and update, ensuring consistent access to the latest context information across the system. -- **Context Versioning and Invalidation**: Implementing versioning and invalidation mechanisms to ensure that cached context data remains fresh and consistent, avoiding stale or outdated information from propagating through the system. - - -### Principle 3: Leverage Agent Specialization ------------------------------------------- - -One of the key advantages of multi-agent architectures is the ability to optimize individual agents for specific tasks, domains, or capabilities. By leveraging agent specialization, enterprises can ensure that each component of their LLM system is finely tuned for maximum performance and quality. - -### Task-Specific Optimization - -Within a multi-agent LLM deployment, different agents may be responsible for distinct tasks such as language understanding, knowledge retrieval, response generation, or post-processing. Optimizing each agent for its designated task can yield significant performance gains and quality improvements. - -Techniques for task-specific optimization include: - -- **Prompt Engineering**: Crafting carefully designed prompts that provide the necessary context, instructions, and examples to guide an agent towards optimal performance for its assigned task. -- **Fine-Tuning**: Adapting a pre-trained LLM to a specific task or domain by fine-tuning it on a curated dataset, allowing the agent to specialize and improve its performance on that particular workload. -- **Model Distillation**: Transferring the knowledge and capabilities of a larger, more capable LLM into a smaller, more efficient model specialized for a specific task, balancing performance and quality trade-offs. - -Implementing these optimization techniques requires a deep understanding of the capabilities and requirements of each task within your multi-agent system, as well as access to relevant training data and computational resources for fine-tuning and distillation processes. - -### Domain Adaptation - -Many enterprise applications operate within specific domains or verticals, such as finance, healthcare, or legal. Adapting agents to these specialized domains can significantly improve their performance, accuracy, and compliance within the target domain. - -Strategies for domain adaptation include: - -- **Domain-Specific Pre-Training**: Leveraging domain-specific corpora to pre-train LLM agents, imbuing them with a foundational understanding of the language, concepts, and nuances specific to the target domain. -- **Transfer Learning**: Fine-tuning agents that have been pre-trained on general or adjacent domains, transferring their existing knowledge and capabilities to the target domain while optimizing for its specific characteristics. -- **Domain Persona Injection**: Injecting domain-specific personas, traits, or constraints into agents during fine-tuning or deployment, shaping their behavior and outputs to align with domain-specific norms and requirements. - -Effective domain adaptation requires access to high-quality, domain-specific training data, as well as close collaboration with subject matter experts to ensure that agents are properly calibrated to meet the unique demands of the target domain. - -### Ensemble Techniques - -In complex multi-agent deployments, individual agents may excel at specific subtasks or aspects of the overall workflow. Ensemble techniques that combine the outputs or predictions of multiple specialized agents can often outperform any single agent, leveraging the collective strengths of the ensemble. - -Common ensemble techniques for multi-agent LLM systems include: - -- **Voting**: Combining the outputs or predictions of multiple agents through majority voting, weighted voting, or other consensus mechanisms. -- **Stacking**: Training a meta-agent to combine and optimize the outputs of multiple base agents, effectively learning to leverage their collective strengths. -- **Blending**: Combining the outputs of multiple agents through weighted averaging, linear interpolation, or other blending techniques, allowing for nuanced integration of diverse perspectives. - -Implementing effective ensemble techniques requires careful analysis of the strengths, weaknesses, and complementary capabilities of individual agents, as well as the development of robust combination strategies that can optimally leverage the ensemble's collective intelligence. - -### Principle 4: Implement Dynamic Scaling --------------------------------------- - -The demand and workload patterns of enterprise LLM deployments can be highly dynamic, with significant fluctuations driven by factors such as user activity, data ingestion schedules, or periodic batch processing. Implementing dynamic scaling strategies allows organizations to optimally provision and allocate resources in response to these fluctuations, ensuring consistent performance while minimizing unnecessary costs. - -### Autoscaling - -Autoscaling is a core capability that enables the automatic adjustment of compute resources (e.g., CPU, GPU, memory) and agent instances based on real-time demand patterns and workload metrics. By dynamically scaling resources up or down, enterprises can maintain optimal performance and resource utilization, avoiding both over-provisioning and under-provisioning scenarios. - -Effective autoscaling in multi-agent LLM deployments requires: - -- **Monitoring and Metrics**: Implementing robust monitoring and metrics collection mechanisms to track key performance indicators (KPIs) such as request rates, response times, resource utilization, and agent-level metrics. -- **Scaling Policies**: Defining scaling policies that specify the conditions and thresholds for triggering automatic scaling actions, such as provisioning additional agents or compute resources when certain KPIs are breached. -- **Scaling Orchestration**: Integrating autoscaling capabilities with resource orchestration and management tools (e.g., Kubernetes, AWS Auto Scaling) to seamlessly provision, configure, and integrate new resources into the existing multi-agent deployment. - -By automating the scaling process, enterprises can respond rapidly to workload fluctuations, ensuring consistent performance and optimal resource utilization without the need for manual intervention. - -### Spot Instance Utilization - -Many cloud providers offer spot instances or preemptible resources at significantly discounted prices compared to on-demand or reserved instances. While these resources may be reclaimed with little notice, they can be leveraged judiciously within multi-agent LLM deployments to reduce operational costs. - -Strategies for leveraging spot instances include: - -- **Fault-Tolerant Agent Deployment**: Deploying certain agents or components of the multi-agent system on spot instances, while ensuring that these components can be rapidly and seamlessly replaced or migrated in the event of instance preemption. -- **Batch Workload Offloading**: Offloading batch processing workloads or non-time-sensitive tasks to spot instances, leveraging their cost-effectiveness while minimizing the impact of potential disruptions. -- **Hybrid Provisioning**: Implementing a hybrid approach that combines on-demand or reserved instances for mission-critical components with spot instances for more flexible or elastic workloads. - -Effective spot instance utilization requires careful architectural considerations to ensure fault tolerance and minimize the impact of potential disruptions, as well as robust monitoring and automation capabilities to seamlessly replace or migrate workloads in response to instance preemption events. - -### Serverless Deployments - -Serverless computing platforms, such as AWS Lambda, Google Cloud Functions, or Azure Functions, offer a compelling alternative to traditional server-based deployments. By automatically scaling compute resources based on real-time demand and charging only for the resources consumed, serverless architectures can provide significant cost savings and operational simplicity. - -Leveraging serverless deployments for multi-agent LLM systems can be achieved through: - -- **Function-as-a-Service (FaaS) Agents**: Deploying individual agents or components of the multi-agent system as serverless functions, allowing for rapid and automatic scaling in response to fluctuating workloads. -- **Event-Driven Architectures**: Designing the multi-agent system to operate in an event-driven manner, with agents triggered and executed in response to specific events or data ingestion, aligning with the serverless execution model. -- **Hybrid Deployments**: Combining serverless components with traditional server-based components, leveraging the strengths and cost advantages of each deployment model for different aspects of the multi-agent system. - -Adopting serverless architectures requires careful consideration of factors such as execution duration limits, cold start latencies, and integration with other components of the multi-agent deployment. However, when implemented effectively, serverless deployments can provide unparalleled scalability, cost-efficiency, and operational simplicity for dynamic, event-driven workloads. - - -### Principle 5: Employ Selective Execution ---------------------------------------- - -Not every input or request within a multi-agent LLM deployment requires the full execution of all agents or the complete processing pipeline. Selectively invoking agents or tasks based on input characteristics or intermediate results can significantly optimize performance by avoiding unnecessary computation and resource consumption. - -### Input Filtering - -Implementing input filtering mechanisms allows enterprises to reject or bypass certain inputs before they are processed by the multi-agent system. This can be achieved through techniques such as: - -- **Blacklisting/Whitelisting**: Maintaining lists of inputs (e.g., specific phrases, URLs, or content types) that should be automatically rejected or allowed, based on predefined criteria. -- **Rules-Based Filtering**: Defining a set of rules or heuristics to assess the suitability or relevance of an input for further processing, based on factors such as language, content, or metadata. -- **Confidence Thresholding**: Leveraging pre-processing agents or models to assess the likelihood that an input is relevant or valuable, and filtering out inputs that fall below a predetermined confidence threshold. - -Effective input filtering requires careful consideration of the specific requirements, constraints, and objectives of your multi-agent deployment, as well as ongoing monitoring and adjustment of filtering rules and thresholds to maintain optimal performance and accuracy. - -### Early Stopping - -In many multi-agent LLM deployments, intermediate results or predictions generated by early-stage agents can be used to determine whether further processing is required or valuable. Early stopping mechanisms allow enterprises to terminate execution pipelines when specific conditions or thresholds are met, avoiding unnecessary downstream processing. - -Techniques for implementing early stopping include: - -- **Confidence-Based Stopping**: Monitoring the confidence scores or probabilities associated with intermediate results, and terminating execution if a predefined confidence threshold is exceeded. -- **Exception-Based Stopping**: Defining specific intermediate results or conditions that indicate that further processing is unnecessary or undesirable, and terminating execution upon encountering these exceptions. -- **Adaptive Stopping**: Employing machine learning models or reinforcement learning agents to dynamically determine when to terminate execution based on learned patterns and trade-offs between accuracy, latency, and resource consumption. - -Effective early stopping requires a deep understanding of the interdependencies and decision points within your multi-agent workflow, as well as careful tuning and monitoring to ensure that stopping conditions are calibrated to maintain an optimal balance between performance and accuracy. - -### Conditional Branching - -Rather than executing a linear, fixed pipeline of agents, conditional branching allows multi-agent systems to dynamically invoke different agents or execution paths based on input characteristics or intermediate results. This can significantly optimize resource utilization by ensuring that only the necessary agents and processes are executed for a given input or scenario. - -Implementing conditional branching involves: - -- **Decision Points**: Identifying key points within the multi-agent workflow where branching decisions can be made based on input or intermediate data. -- **Branching Logic**: Defining the rules, conditions, or machine learning models that will evaluate the input or intermediate data and determine the appropriate execution path or agent invocation. -- **Execution Routing**: Integrating mechanisms to dynamically route inputs or intermediate data to the appropriate agents or processes based on the branching decision. - -Conditional branching can be particularly effective in scenarios where inputs or workloads exhibit distinct characteristics or require significantly different processing pipelines, allowing enterprises to optimize resource allocation and minimize unnecessary computation. - -### Principle 6: Optimize User Experience -------------------------------------- - -While many of the principles outlined in this guide focus on optimizing backend performance and resource utilization, delivering an exceptional user experience is also a critical consideration for enterprise multi-agent LLM deployments. By minimizing perceived wait times and providing real-time progress updates, organizations can ensure that users remain engaged and satisfied, even during periods of high workload or resource constraints. - -### Streaming Responses - -One of the most effective techniques for minimizing perceived wait times is to stream responses or outputs to users as they are generated, rather than waiting for the entire response to be completed before delivering it. This approach is particularly valuable in conversational agents, document summarization, or other scenarios where outputs can be naturally segmented and delivered incrementally. - -Implementing streaming responses requires: - -- **Partial Output Generation**: Modifying agents or models to generate and emit outputs in a streaming or incremental fashion, rather than producing the entire output in a single, monolithic operation. -- **Streaming Data Pipelines**: Integrating streaming data pipelines and message queues to enable the efficient and reliable transmission of partial outputs from agents to user-facing interfaces or applications. -- **Incremental Rendering**: Updating user interfaces and displays to incrementally render or populate with newly streamed output segments, providing a seamless and real-time experience for end-users. - -By delivering outputs as they are generated, streaming responses can significantly improve the perceived responsiveness and interactivity of multi-agent LLM deployments, even in scenarios where the overall processing time remains unchanged. - -### Progress Indicators - -In cases where streaming responses may not be feasible or appropriate, providing visual or textual indicators of ongoing processing and progress can help manage user expectations and improve the overall experience. Progress indicators can be implemented through techniques such as: - -- **Loader Animations**: Displaying simple animations or spinner graphics to indicate that processing is underway and provide a sense of activity and progress. -- **Progress Bars**: Rendering progress bars or completion indicators based on estimated or actual progress through multi-agent workflows or processing pipelines. -- **Status Updates**: Periodically updating user interfaces with textual status messages or descriptions of the current processing stage, providing users with a more detailed understanding of the system's activities. - -Effective progress indicators require careful integration with monitoring and telemetry capabilities to accurately track and communicate the progress of multi-agent workflows, as well as thoughtful user experience design to ensure that indicators are clear, unobtrusive, and aligned with user expectations. - -### Chunked Delivery - -In scenarios where outputs or responses cannot be effectively streamed or rendered incrementally, chunked delivery can provide a middle ground between delivering the entire output at once and streaming individual tokens or characters. By breaking larger outputs into smaller, more manageable chunks and delivering them individually, enterprises can improve perceived responsiveness and provide a more engaging user experience. - -Implementing chunked delivery involves: - -- **Output Segmentation**: Identifying logical breakpoints or segmentation boundaries within larger outputs, such as paragraphs, sections, or other structural elements. -- **Chunking Mechanisms**: Integrating mechanisms to efficiently break outputs into individual chunks and transmit or render them sequentially, with minimal delay between chunks. -- **Chunk Rendering**: Updating user interfaces or displays to seamlessly render or append new output chunks as they are received, providing a sense of continuous progress and minimizing the perception of extended waiting periods. - -Chunked delivery can be particularly effective in scenarios where outputs are inherently structured or segmented, such as document generation, report creation, or multi-step instructions or workflows. - -## Principle 7: Leverage Hybrid Approaches ---------------------------------------- - -While multi-agent LLM architectures offer numerous advantages, they should not be viewed as a one-size-fits-all solution. In many cases, combining LLM agents with traditional techniques, optimized components, or external services can yield superior performance, cost-effectiveness, and resource utilization compared to a pure LLM-based approach. - -### Task Offloading - -Certain tasks or subtasks within a larger multi-agent workflow may be more efficiently handled by dedicated, optimized components or external services, rather than relying solely on LLM agents. Task offloading involves identifying these opportunities and integrating the appropriate components or services into the overall architecture. - -Examples of task offloading in multi-agent LLM deployments include: - -- **Regular Expression Matching**: Offloading pattern matching or text extraction tasks to dedicated regular expression engines, which can often outperform LLM-based approaches in terms of speed and efficiency. -- **Structured Data Processing**: Leveraging specialized data processing engines or databases for tasks involving structured data, such as querying, filtering, or transforming tabular or relational data. -- **External APIs and Services**: Integrating with external APIs or cloud services for specific tasks, such as speech recognition, translation, or knowledge base lookup, leveraging the specialized capabilities and optimizations of these dedicated services. - -Effective task offloading requires a thorough understanding of the strengths and limitations of both LLM agents and traditional components, as well as careful consideration of integration points, data flows, and performance trade-offs within the overall multi-agent architecture. - -### Caching and Indexing - -While LLMs excel at generating dynamic, context-aware outputs, they can be less efficient when dealing with static or frequently accessed information or knowledge. Caching and indexing strategies can help mitigate this limitation by minimizing redundant LLM processing and enabling faster retrieval of commonly accessed data. - -Techniques for leveraging caching and indexing in multi-agent LLM deployments include: - -**Output Caching**: Caching the outputs or responses generated by LLM agents, allowing for rapid retrieval and reuse in cases where the same or similar input is encountered in the future. - -**Knowledge Base Indexing**: Indexing domain-specific knowledge bases, data repositories, or other static information sources using traditional search and information retrieval techniques. This allows LLM agents to efficiently query and incorporate relevant information into their outputs, without needing to process or generate this content from scratch. - -**Contextual Caching**: Caching not only outputs but also the contextual information and intermediate results generated during multi-agent workflows. This enables more efficient reuse and continuation of previous processing in scenarios where contexts are long-lived or recurring. - -Implementing effective caching and indexing strategies requires careful consideration of data freshness, consistency, and invalidation mechanisms, as well as seamless integration with LLM agents and multi-agent workflows to ensure that cached or indexed data is appropriately leveraged and updated. - -### Pre-computation and Lookup - -In certain scenarios, especially those involving constrained or well-defined inputs, pre-computing and lookup strategies can be leveraged to minimize or entirely avoid the need for real-time LLM processing. By generating and storing potential outputs or responses in advance, enterprises can significantly improve performance and reduce resource consumption. - -Approaches for pre-computation and lookup include: - -**Output Pre-generation**: For inputs or scenarios with a limited set of potential outputs, pre-generating and storing all possible responses, allowing for rapid retrieval and delivery without the need for real-time LLM execution. - -**Retrieval-Based Responses**: Developing retrieval models or techniques that can identify and surface pre-computed or curated responses based on input characteristics, leveraging techniques such as nearest neighbor search, embedding-based retrieval, or example-based generation. - -**Hybrid Approaches**: Combining pre-computed or retrieved responses with real-time LLM processing, allowing for the generation of dynamic, context-aware content while still leveraging pre-computed components to optimize performance and resource utilization. - -Effective implementation of pre-computation and lookup strategies requires careful analysis of input patterns, output distributions, and potential performance gains, as well as robust mechanisms for managing and updating pre-computed data as application requirements or domain knowledge evolves. - -# Conclusion ----------- - -As enterprises increasingly embrace the transformative potential of large language models, optimizing the performance, scalability, and cost-effectiveness of these deployments has become a critical imperative. Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLM agents, offer a powerful paradigm for addressing these challenges. - -By implementing the seven principles outlined in this guide -- distributing token processing, optimizing agent communication, leveraging agent specialization, implementing dynamic scaling, employing selective execution, optimizing user experience, and leveraging hybrid approaches -- organizations can unlock the full potential of multi-agent LLM deployments. - -However, realizing these benefits requires a strategic and holistic approach that accounts for the unique requirements, constraints, and objectives of each enterprise. From task-specific optimizations and domain adaptation to dynamic scaling and user experience considerations, maximizing the performance of multi-agent LLM systems demands a deep understanding of the underlying technologies, as well as the ability to navigate the inherent complexities of these sophisticated architectures. - -To learn more about how Swarm Corporation can assist your organization in architecting, deploying, and optimizing high-performance multi-agent LLM solutions, we invite you to book a consultation with one of our agent specialists. Visit to schedule a 30-minute call and explore how our expertise and cutting-edge technologies can drive transformative outcomes for your business. - -In the rapidly evolving landscape of artificial intelligence and natural language processing, staying ahead of the curve is essential. Partner with Swarm Corporation, and unlock the full potential of multi-agent LLM deployments, today. - -[Book a call with us now:](https://calendly.com/swarm-corp/30min) \ No newline at end of file diff --git a/docs/swarms_cloud/python_client.md b/docs/swarms_cloud/python_client.md deleted file mode 100644 index f24bd780..00000000 --- a/docs/swarms_cloud/python_client.md +++ /dev/null @@ -1,779 +0,0 @@ -# Swarms Cloud API Client Documentation - -## Introduction - -The Swarms Cloud API client is a production-grade Python package for interacting with the Swarms API. It provides both synchronous and asynchronous interfaces, making it suitable for a wide range of applications from simple scripts to high-performance, scalable services. - -Key features include: -- Connection pooling and efficient session management -- Automatic retries with exponential backoff -- Circuit breaker pattern for improved reliability -- In-memory caching for frequently accessed resources -- Comprehensive error handling with detailed exceptions -- Full support for asynchronous operations -- Type checking with Pydantic - -This documentation covers all available client methods with detailed descriptions, parameter references, and usage examples. - -## Installation - -```bash -pip install swarms-client -``` - -## Authentication - -To use the Swarms API, you need an API key. You can obtain your API key from the [Swarms Platform API Keys page](https://swarms.world/platform/api-keys). - -## Client Initialization - -The `SwarmsClient` is the main entry point for interacting with the Swarms API. It can be initialized with various configuration options to customize its behavior. - -```python -from swarms_client import SwarmsClient - -# Initialize with default settings -client = SwarmsClient(api_key="your-api-key") - -# Or with custom settings -client = SwarmsClient( - api_key="your-api-key", - base_url="https://swarms-api-285321057562.us-east1.run.app", - timeout=60, - max_retries=3, - retry_delay=1, - log_level="INFO", - pool_connections=100, - pool_maxsize=100, - keep_alive_timeout=5, - max_concurrent_requests=100, - circuit_breaker_threshold=5, - circuit_breaker_timeout=60, - enable_cache=True -) -``` - -### Parameters - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `api_key` | `str` | Environment variable `SWARMS_API_KEY` | API key for authentication | -| `base_url` | `str` | `"https://swarms-api-285321057562.us-east1.run.app"` | Base URL for the API | -| `timeout` | `int` | `60` | Timeout for API requests in seconds | -| `max_retries` | `int` | `3` | Maximum number of retry attempts for failed requests | -| `retry_delay` | `int` | `1` | Initial delay between retries in seconds (uses exponential backoff) | -| `log_level` | `str` | `"INFO"` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | -| `pool_connections` | `int` | `100` | Number of connection pools to cache | -| `pool_maxsize` | `int` | `100` | Maximum number of connections to save in the pool | -| `keep_alive_timeout` | `int` | `5` | Keep-alive timeout for connections in seconds | -| `max_concurrent_requests` | `int` | `100` | Maximum number of concurrent requests | -| `circuit_breaker_threshold` | `int` | `5` | Failure threshold for the circuit breaker | -| `circuit_breaker_timeout` | `int` | `60` | Reset timeout for the circuit breaker in seconds | -| `enable_cache` | `bool` | `True` | Whether to enable in-memory caching | - -## Client Methods - -### clear_cache - -Clears the in-memory cache used for caching API responses. - -```python -client.clear_cache() -``` - -## Agent Resource - -The Agent resource provides methods for creating and managing agent completions. - - -### create - -Creates an agent completion. - -```python -response = client.agent.create( - agent_config={ - "agent_name": "Researcher", - "description": "Conducts in-depth research on topics", - "model_name": "gpt-4o", - "temperature": 0.7 - }, - task="Research the latest advancements in quantum computing and summarize the key findings" -) - -print(f"Agent ID: {response.id}") -print(f"Output: {response.outputs}") -``` - -#### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `agent_config` | `dict` or `AgentSpec` | Yes | Configuration for the agent | -| `task` | `str` | Yes | The task for the agent to complete | -| `history` | `dict` | No | Optional conversation history | - -The `agent_config` parameter can include the following fields: - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `agent_name` | `str` | Required | Name of the agent | -| `description` | `str` | `None` | Description of the agent's purpose | -| `system_prompt` | `str` | `None` | System prompt to guide the agent's behavior | -| `model_name` | `str` | `"gpt-4o-mini"` | Name of the model to use | -| `auto_generate_prompt` | `bool` | `False` | Whether to automatically generate a prompt | -| `max_tokens` | `int` | `8192` | Maximum tokens in the response | -| `temperature` | `float` | `0.5` | Temperature for sampling (0-1) | -| `role` | `str` | `None` | Role of the agent | -| `max_loops` | `int` | `1` | Maximum number of reasoning loops | -| `tools_dictionary` | `List[Dict]` | `None` | Tools available to the agent | - -#### Returns - -`AgentCompletionResponse` object with the following properties: - -- `id`: Unique identifier for the completion -- `success`: Whether the completion was successful -- `name`: Name of the agent -- `description`: Description of the agent -- `temperature`: Temperature used for the completion -- `outputs`: Output from the agent -- `usage`: Token usage information -- `timestamp`: Timestamp of the completion - - -### create_batch - -Creates multiple agent completions in batch. - -```python -responses = client.agent.create_batch([ - { - "agent_config": { - "agent_name": "Researcher", - "model_name": "gpt-4o-mini", - "temperature": 0.5 - }, - "task": "Summarize the latest quantum computing research" - }, - { - "agent_config": { - "agent_name": "Writer", - "model_name": "gpt-4o", - "temperature": 0.7 - }, - "task": "Write a blog post about AI safety" - } -]) - -for i, response in enumerate(responses): - print(f"Agent {i+1} ID: {response.id}") - print(f"Output: {response.outputs}") - print("---") -``` - -#### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `completions` | `List[Dict or AgentCompletion]` | Yes | List of agent completion requests | - -Each item in the `completions` list should have the same structure as the parameters for the `create` method. - -#### Returns - -List of `AgentCompletionResponse` objects with the same properties as the return value of the `create` method. - - -### acreate - -Creates an agent completion asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - response = await client.agent.acreate( - agent_config={ - "agent_name": "Researcher", - "description": "Conducts in-depth research", - "model_name": "gpt-4o" - }, - task="Research the impact of quantum computing on cryptography" - ) - - print(f"Agent ID: {response.id}") - print(f"Output: {response.outputs}") - -asyncio.run(main()) -``` - -#### Parameters - -Same as the `create` method. - -#### Returns - -Same as the `create` method. - - -### acreate_batch - -Creates multiple agent completions in batch asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - responses = await client.agent.acreate_batch([ - { - "agent_config": { - "agent_name": "Researcher", - "model_name": "gpt-4o-mini" - }, - "task": "Summarize the latest quantum computing research" - }, - { - "agent_config": { - "agent_name": "Writer", - "model_name": "gpt-4o" - }, - "task": "Write a blog post about AI safety" - } - ]) - - for i, response in enumerate(responses): - print(f"Agent {i+1} ID: {response.id}") - print(f"Output: {response.outputs}") - print("---") - -asyncio.run(main()) -``` - -#### Parameters - -Same as the `create_batch` method. - -#### Returns - -Same as the `create_batch` method. - -## Swarm Resource - -The Swarm resource provides methods for creating and managing swarm completions. - - -### create - -Creates a swarm completion. - -```python -response = client.swarm.create( - name="Research Swarm", - description="A swarm for research tasks", - swarm_type="SequentialWorkflow", - task="Research quantum computing advances in 2024 and summarize the key findings", - agents=[ - { - "agent_name": "Researcher", - "description": "Conducts in-depth research", - "model_name": "gpt-4o", - "temperature": 0.5 - }, - { - "agent_name": "Critic", - "description": "Evaluates arguments for flaws", - "model_name": "gpt-4o-mini", - "temperature": 0.3 - } - ], - max_loops=3, - return_history=True -) - -print(f"Job ID: {response.job_id}") -print(f"Status: {response.status}") -print(f"Output: {response.output}") -``` - -#### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | `str` | No | Name of the swarm | -| `description` | `str` | No | Description of the swarm | -| `agents` | `List[Dict or AgentSpec]` | No | List of agent specifications | -| `max_loops` | `int` | No | Maximum number of loops (default: 1) | -| `swarm_type` | `str` | No | Type of swarm (see available types) | -| `task` | `str` | Conditional | The task to complete (required if tasks and messages are not provided) | -| `tasks` | `List[str]` | Conditional | List of tasks for batch processing (required if task and messages are not provided) | -| `messages` | `List[Dict]` | Conditional | List of messages to process (required if task and tasks are not provided) | -| `return_history` | `bool` | No | Whether to return the execution history (default: True) | -| `rules` | `str` | No | Rules for the swarm | -| `schedule` | `Dict` | No | Schedule specification for delayed execution | -| `stream` | `bool` | No | Whether to stream the response (default: False) | -| `service_tier` | `str` | No | Service tier ('standard' or 'flex', default: 'standard') | - -#### Returns - -`SwarmCompletionResponse` object with the following properties: - -- `job_id`: Unique identifier for the job -- `status`: Status of the job -- `swarm_name`: Name of the swarm -- `description`: Description of the swarm -- `swarm_type`: Type of swarm used -- `output`: Output from the swarm -- `number_of_agents`: Number of agents in the swarm -- `service_tier`: Service tier used -- `tasks`: List of tasks processed (if applicable) -- `messages`: List of messages processed (if applicable) - - -### create_batch - -Creates multiple swarm completions in batch. - -```python -responses = client.swarm.create_batch([ - { - "name": "Research Swarm", - "swarm_type": "auto", - "task": "Research quantum computing advances", - "agents": [ - {"agent_name": "Researcher", "model_name": "gpt-4o"} - ] - }, - { - "name": "Writing Swarm", - "swarm_type": "SequentialWorkflow", - "task": "Write a blog post about AI safety", - "agents": [ - {"agent_name": "Writer", "model_name": "gpt-4o"}, - {"agent_name": "Editor", "model_name": "gpt-4o-mini"} - ] - } -]) - -for i, response in enumerate(responses): - print(f"Swarm {i+1} Job ID: {response.job_id}") - print(f"Status: {response.status}") - print(f"Output: {response.output}") - print("---") -``` - -#### Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `swarms` | `List[Dict or SwarmSpec]` | Yes | List of swarm specifications | - -Each item in the `swarms` list should have the same structure as the parameters for the `create` method. - -#### Returns - -List of `SwarmCompletionResponse` objects with the same properties as the return value of the `create` method. - - -### list_types - -Lists available swarm types. - -```python -response = client.swarm.list_types() - -print(f"Available swarm types:") -for swarm_type in response.swarm_types: - print(f"- {swarm_type}") -``` - -#### Returns - -`SwarmTypesResponse` object with the following properties: - -- `success`: Whether the request was successful -- `swarm_types`: List of available swarm types - - -### alist_types - -Lists available swarm types asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - response = await client.swarm.alist_types() - - print(f"Available swarm types:") - for swarm_type in response.swarm_types: - print(f"- {swarm_type}") - -asyncio.run(main()) -``` - -#### Returns - -Same as the `list_types` method. - - -### acreate - -Creates a swarm completion asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - response = await client.swarm.acreate( - name="Research Swarm", - swarm_type="SequentialWorkflow", - task="Research quantum computing advances in 2024", - agents=[ - { - "agent_name": "Researcher", - "description": "Conducts in-depth research", - "model_name": "gpt-4o" - }, - { - "agent_name": "Critic", - "description": "Evaluates arguments for flaws", - "model_name": "gpt-4o-mini" - } - ] - ) - - print(f"Job ID: {response.job_id}") - print(f"Status: {response.status}") - print(f"Output: {response.output}") - -asyncio.run(main()) -``` - -#### Parameters - -Same as the `create` method. - -#### Returns - -Same as the `create` method. - - -### acreate_batch - -Creates multiple swarm completions in batch asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - responses = await client.swarm.acreate_batch([ - { - "name": "Research Swarm", - "swarm_type": "auto", - "task": "Research quantum computing", - "agents": [ - {"agent_name": "Researcher", "model_name": "gpt-4o"} - ] - }, - { - "name": "Writing Swarm", - "swarm_type": "SequentialWorkflow", - "task": "Write a blog post about AI safety", - "agents": [ - {"agent_name": "Writer", "model_name": "gpt-4o"} - ] - } - ]) - - for i, response in enumerate(responses): - print(f"Swarm {i+1} Job ID: {response.job_id}") - print(f"Status: {response.status}") - print(f"Output: {response.output}") - print("---") - -asyncio.run(main()) -``` - -#### Parameters - -Same as the `create_batch` method. - -#### Returns - -Same as the `create_batch` method. - -## Models Resource - -The Models resource provides methods for retrieving information about available models. - - -### list - -Lists available models. - -```python -response = client.models.list() - -print(f"Available models:") -for model in response.models: - print(f"- {model}") -``` - -#### Returns - -`ModelsResponse` object with the following properties: - -- `success`: Whether the request was successful -- `models`: List of available model names - - -### alist - -Lists available models asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient(api_key="your-api-key") as client: - response = await client.models.alist() - - print(f"Available models:") - for model in response.models: - print(f"- {model}") - -asyncio.run(main()) -``` - -#### Returns - -Same as the `list` method. - -## Logs Resource - -The Logs resource provides methods for retrieving API request logs. - - -### list - -Lists API request logs. - -```python -response = client.logs.list() - -print(f"Found {response.count} logs:") -for log in response.logs: - print(f"- ID: {log.id}, Created at: {log.created_at}") - print(f" Data: {log.data}") -``` - -#### Returns - -`LogsResponse` object with the following properties: - -- `status`: Status of the request -- `count`: Number of logs -- `logs`: List of log entries -- `timestamp`: Timestamp of the request - -Each log entry is a `LogEntry` object with the following properties: - -- `id`: Unique identifier for the log entry -- `api_key`: API key used for the request -- `data`: Request data -- `created_at`: Timestamp when the log entry was created - - -### alist - -Lists API request logs asynchronously. - -```python -import asyncio -from swarms_client import SwarmsClient - -async def main(): - async with SwarmsClient() as client: - response = await client.logs.alist() - - print(f"Found {response.count} logs:") - for log in response.logs: - print(f"- ID: {log.id}, Created at: {log.created_at}") - print(f" Data: {log.data}") - -asyncio.run(main()) -``` - -#### Returns - -Same as the `list` method. - -## Error Handling - -The Swarms API client provides detailed error handling with specific exception types for different error scenarios. All exceptions inherit from the base `SwarmsError` class. - -```python -from swarms_client import SwarmsClient, SwarmsError, AuthenticationError, RateLimitError, APIError - -try: - client = SwarmsClient(api_key="invalid-api-key") - response = client.agent.create( - agent_config={"agent_name": "Researcher", "model_name": "gpt-4o"}, - task="Research quantum computing" - ) -except AuthenticationError as e: - print(f"Authentication error: {e}") -except RateLimitError as e: - print(f"Rate limit exceeded: {e}") -except APIError as e: - print(f"API error: {e}") -except SwarmsError as e: - print(f"Swarms error: {e}") -``` - -### Exception Types - -| Exception | Description | -|-----------|-------------| -| `SwarmsError` | Base exception for all Swarms API errors | -| `AuthenticationError` | Raised when there's an issue with authentication | -| `RateLimitError` | Raised when the rate limit is exceeded | -| `APIError` | Raised when the API returns an error | -| `InvalidRequestError` | Raised when the request is invalid | -| `InsufficientCreditsError` | Raised when the user doesn't have enough credits | -| `TimeoutError` | Raised when a request times out | -| `NetworkError` | Raised when there's a network issue | - -## Advanced Features - -### Connection Pooling - -The Swarms API client uses connection pooling to efficiently manage HTTP connections, which can significantly improve performance when making multiple requests. - -```python -client = SwarmsClient( - api_key="your-api-key", - pool_connections=100, # Number of connection pools to cache - pool_maxsize=100, # Maximum number of connections to save in the pool - keep_alive_timeout=5 # Keep-alive timeout for connections in seconds -) -``` - -### Circuit Breaker Pattern - -The client implements the circuit breaker pattern to prevent cascading failures when the API is experiencing issues. - -```python -client = SwarmsClient( - api_key="your-api-key", - circuit_breaker_threshold=5, # Number of failures before the circuit opens - circuit_breaker_timeout=60 # Time in seconds before attempting to close the circuit -) -``` - -### Caching - -The client includes in-memory caching for frequently accessed resources to reduce API calls and improve performance. - -```python -client = SwarmsClient( - api_key="your-api-key", - enable_cache=True # Enable in-memory caching -) - -# Clear the cache manually if needed -client.clear_cache() -``` - -## Complete Example - -Here's a complete example that demonstrates how to use the Swarms API client to create a research swarm and process its output: - -```python -import os -from swarms_client import SwarmsClient -from dotenv import load_dotenv - -# Load API key from environment -load_dotenv() -api_key = os.getenv("SWARMS_API_KEY") - -# Initialize client -client = SwarmsClient(api_key=api_key) - -# Create a research swarm -try: - # Define the agents - researcher = { - "agent_name": "Researcher", - "description": "Conducts thorough research on specified topics", - "model_name": "gpt-4o", - "temperature": 0.5, - "system_prompt": "You are a diligent researcher focused on finding accurate and comprehensive information." - } - - analyst = { - "agent_name": "Analyst", - "description": "Analyzes research findings and identifies key insights", - "model_name": "gpt-4o", - "temperature": 0.3, - "system_prompt": "You are an insightful analyst who can identify patterns and extract meaningful insights from research data." - } - - summarizer = { - "agent_name": "Summarizer", - "description": "Creates concise summaries of complex information", - "model_name": "gpt-4o-mini", - "temperature": 0.4, - "system_prompt": "You specialize in distilling complex information into clear, concise summaries." - } - - # Create the swarm - response = client.swarm.create( - name="Quantum Computing Research Swarm", - description="A swarm for researching and analyzing quantum computing advancements", - swarm_type="SequentialWorkflow", - task="Research the latest advancements in quantum computing in 2024, analyze their potential impact on cryptography and data security, and provide a concise summary of the findings.", - agents=[researcher, analyst, summarizer], - max_loops=2, - return_history=True - ) - - # Process the response - print(f"Job ID: {response.job_id}") - print(f"Status: {response.status}") - print(f"Number of agents: {response.number_of_agents}") - print(f"Swarm type: {response.swarm_type}") - - # Print the output - if "final_output" in response.output: - print("\nFinal Output:") - print(response.output["final_output"]) - else: - print("\nOutput:") - print(response.output) - - # Access agent-specific outputs if available - if "agent_outputs" in response.output: - print("\nAgent Outputs:") - for agent, output in response.output["agent_outputs"].items(): - print(f"\n{agent}:") - print(output) - -except Exception as e: - print(f"Error: {e}") -``` - -This example creates a sequential workflow swarm with three agents to research quantum computing, analyze the findings, and create a summary of the results. diff --git a/docs/swarms_cloud/quickstart.md b/docs/swarms_cloud/quickstart.md deleted file mode 100644 index 438b81f0..00000000 --- a/docs/swarms_cloud/quickstart.md +++ /dev/null @@ -1,1165 +0,0 @@ - -# 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/EamjgSaEQf) | -| 🐦 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 deleted file mode 100644 index 69f68688..00000000 --- a/docs/swarms_cloud/rate_limits.md +++ /dev/null @@ -1,196 +0,0 @@ -# Swarms API Rate Limits - -The Swarms API implements a comprehensive rate limiting system that tracks API requests across multiple time windows and enforces various limits to ensure fair usage and system stability. - -## Rate Limits Summary - -| Rate Limit Type | Free Tier | Premium Tier | Time Window | Description | -|----------------|-----------|--------------|-------------|-------------| -| **Requests per Minute** | 100 | 2,000 | 1 minute | Maximum API calls per minute | -| **Requests per Hour** | 50 | 10,000 | 1 hour | Maximum API calls per hour | -| **Requests per Day** | 1,200 | 100,000 | 24 hours | Maximum API calls per day | -| **Tokens per Agent** | 200,000 | 2,000,000 | Per request | Maximum tokens per agent | -| **Prompt Length** | 200,000 | 200,000 | Per request | Maximum input tokens per request | -| **Batch Size** | 10 | 10 | Per request | Maximum agents in batch requests | -| **IP-based Fallback** | 100 | 100 | 60 seconds | For requests without API keys | - -## Detailed Rate Limit Explanations - -### 1. **Request Rate Limits** - -These limits control how many API calls you can make within specific time windows. - -#### **Per-Minute Limit** - -| Tier | Requests per Minute | Reset Interval | Applies To | -|--------------|--------------------|------------------------|--------------------| -| Free | 100 | Every minute (sliding) | All API endpoints | -| Premium | 2,000 | Every minute (sliding) | All API endpoints | - -#### **Per-Hour Limit** - -- **Free Tier**: 50 requests per hour -- **Premium Tier**: 10,000 requests per hour -- **Reset**: Every hour (sliding window) -- **Applies to**: All API endpoints - -#### **Per-Day Limit** - -- **Free Tier**: 1,200 requests per day (50 × 24) - -- **Premium Tier**: 100,000 requests per day - -- **Reset**: Every 24 hours (sliding window) - -- **Applies to**: All API endpoints - -### 2. **Token Limits** - -These limits control the amount of text processing allowed per request. - -#### **Tokens per Agent** - -- **Free Tier**: 200,000 tokens per agent - -- **Premium Tier**: 2,000,000 tokens per agent - -- **Applies to**: Individual agent configurations - -- **Includes**: System prompts, task descriptions, and agent names - -#### **Prompt Length Limit** - -- **All Tiers**: 200,000 tokens maximum - -- **Applies to**: Combined input text (task + history + system prompts) - -- **Error**: Returns 400 error if exceeded - -- **Message**: "Prompt is too long. Please provide a prompt that is less than 10000 tokens." - -### 3. **Batch Processing Limits** - -These limits control concurrent processing capabilities. - -#### **Batch Size Limit** - -- **All Tiers**: 10 agents maximum per batch - -- **Applies to**: `/v1/agent/batch/completions` endpoint - -- **Error**: Returns 400 error if exceeded - -- **Message**: "ERROR: BATCH SIZE EXCEEDED - You can only run up to 10 batch agents at a time." - -## How Rate Limiting Works - -### Database-Based Tracking - -The system uses a database-based approach for API key requests: - -1. **Request Logging**: Every API request is logged to the `swarms_api_logs` table -2. **Time Window Queries**: The system queries for requests in the last minute, hour, and day -3. **Limit Comparison**: Current counts are compared against configured limits -4. **Request Blocking**: Requests are blocked if any limit is exceeded - -### Sliding Windows - -Rate limits use sliding windows rather than fixed windows: - -- **Minute**: Counts requests in the last 60 seconds - -- **Hour**: Counts requests in the last 60 minutes - -- **Day**: Counts requests in the last 24 hours - -This provides more accurate rate limiting compared to fixed time windows. - -## Checking Your Rate Limits - -### API Endpoint - -Use the `/v1/rate/limits` endpoint to check your current usage: - -```bash -curl -H "x-api-key: your-api-key" \ - https://api.swarms.world/v1/rate/limits -``` - -### Response Format - -```json -{ - "success": true, - "rate_limits": { - "minute": { - "count": 5, - "limit": 100, - "exceeded": false, - "remaining": 95, - "reset_time": "2024-01-15T10:30:00Z" - }, - "hour": { - "count": 25, - "limit": 50, - "exceeded": false, - "remaining": 25, - "reset_time": "2024-01-15T11:00:00Z" - }, - "day": { - "count": 150, - "limit": 1200, - "exceeded": false, - "remaining": 1050, - "reset_time": "2024-01-16T10:00:00Z" - } - }, - "limits": { - "maximum_requests_per_minute": 100, - "maximum_requests_per_hour": 50, - "maximum_requests_per_day": 1200, - "tokens_per_agent": 200000 - }, - "timestamp": "2024-01-15T10:29:30Z" -} -``` - -## Handling Rate Limit Errors - -### Error Response - -When rate limits are exceeded, you'll receive a 429 status code: - -```json -{ - "detail": "Rate limit exceeded for minute window(s). Upgrade to Premium for increased limits (2,000/min, 10,000/hour, 100,000/day) at https://swarms.world/platform/account for just $99/month." -} -``` - -### Best Practices - -1. **Monitor Usage**: Regularly check your rate limits using the `/v1/rate/limits` endpoint -2. **Implement Retry Logic**: Use exponential backoff when hitting rate limits -3. **Optimize Requests**: Combine multiple operations into single requests when possible -4. **Upgrade When Needed**: Consider upgrading to Premium for higher limits - -## Premium Tier Benefits - -Upgrade to Premium for significantly higher limits: - -- **20x more requests per minute** (2,000 vs 100) - -- **200x more requests per hour** (10,000 vs 50) - -- **83x more requests per day** (100,000 vs 1,200) - -- **10x more tokens per agent** (2M vs 200K) - -Visit [Swarms Platform Account](https://swarms.world/platform/account) to upgrade for just $99/month. - -## Performance Considerations - -- Database queries are optimized to only count request IDs -- Rate limit checks are cached per request -- Fallback mechanisms ensure system reliability -- Minimal impact on request latency -- Persistent tracking across server restarts \ No newline at end of file diff --git a/docs/swarms_cloud/rust_client.md b/docs/swarms_cloud/rust_client.md deleted file mode 100644 index ab4d4922..00000000 --- a/docs/swarms_cloud/rust_client.md +++ /dev/null @@ -1,732 +0,0 @@ -# Swarms Client - Production Grade Rust SDK - -A high-performance, production-ready Rust client for the Swarms API with comprehensive features for building multi-agent AI systems. - -## Features - -- **🚀 High Performance**: Built with `reqwest` and `tokio` for maximum throughput -- **🔄 Connection Pooling**: Automatic HTTP connection reuse and pooling -- **⚡ Circuit Breaker**: Automatic failure detection and recovery -- **💾 Intelligent Caching**: TTL-based in-memory caching with concurrent access -- **📊 Rate Limiting**: Configurable concurrent request limits -- **🔄 Retry Logic**: Exponential backoff with jitter -- **📝 Comprehensive Logging**: Structured logging with `tracing` -- **✅ Type Safety**: Full compile-time type checking with `serde` - -## Installation - -Install `swarms-rs` globally using cargo: - -```bash -cargo install swarms-rs -``` - - - - - -## Quick Start - -```rust -use swarms_client::SwarmsClient; - -#[tokio::main] -async fn main() -> Result<(), Box> { - // Initialize the client with API key from environment - let client = SwarmsClient::builder() - .unwrap() - .from_env()? // Loads API key from SWARMS_API_KEY environment variable - .timeout(std::time::Duration::from_secs(60)) - .max_retries(3) - .build()?; - - // Make a simple swarm completion request - let response = client.swarm() - .completion() - .name("My First Swarm") - .swarm_type(SwarmType::Auto) - .task("Analyze the pros and cons of quantum computing") - .agent(|agent| { - agent - .name("Researcher") - .description("Conducts in-depth research") - .model("gpt-4o") - }) - .send() - .await?; - - println!("Swarm output: {}", response.output); - Ok(()) -} -``` - -## API Reference - -### SwarmsClient - -The main client for interacting with the Swarms API. - -#### Constructor Methods - -##### `SwarmsClient::builder()` - -Creates a new client builder for configuring the client. - -**Returns**: `Result` - -**Example**: -```rust -let client = SwarmsClient::builder() - .unwrap() - .api_key("your-api-key") - .timeout(Duration::from_secs(60)) - .build()?; -``` - -##### `SwarmsClient::with_config(config: ClientConfig)` - -Creates a client with custom configuration. - -| Parameter | Type | Description | -|-----------|------|-------------| -| `config` | `ClientConfig` | Client configuration settings | - -**Returns**: `Result` - -**Example**: -```rust -let config = ClientConfig { - api_key: "your-api-key".to_string(), - base_url: "https://api.swarms.com/".parse().unwrap(), - timeout: Duration::from_secs(120), - max_retries: 5, - ..Default::default() -}; - -let client = SwarmsClient::with_config(config)?; -``` - -#### Resource Access Methods - -| Method | Returns | Description | -|--------|---------|-------------| -| `agent()` | `AgentResource` | Access agent-related operations | -| `swarm()` | `SwarmResource` | Access swarm-related operations | -| `models()` | `ModelsResource` | Access model listing operations | -| `logs()` | `LogsResource` | Access logging operations | - -#### Cache Management Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `clear_cache()` | None | `()` | Clears all cached responses | -| `cache_stats()` | None | `Option<(usize, usize)>` | Returns (valid_entries, total_entries) | - -### ClientBuilder - -Builder for configuring the Swarms client. - -#### Configuration Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `new()` | None | `ClientBuilder` | Creates a new builder with defaults | -| `from_env()` | None | `Result` | Loads API key from environment | -| `api_key(key)` | `String` | `ClientBuilder` | Sets the API key | -| `base_url(url)` | `&str` | `Result` | Sets the base URL | -| `timeout(duration)` | `Duration` | `ClientBuilder` | Sets request timeout | -| `max_retries(count)` | `usize` | `ClientBuilder` | Sets maximum retry attempts | -| `retry_delay(duration)` | `Duration` | `ClientBuilder` | Sets retry delay duration | -| `max_concurrent_requests(count)` | `usize` | `ClientBuilder` | Sets concurrent request limit | -| `enable_cache(enabled)` | `bool` | `ClientBuilder` | Enables/disables caching | -| `cache_ttl(duration)` | `Duration` | `ClientBuilder` | Sets cache TTL | -| `build()` | None | `Result` | Builds the client | - -**Example**: -```rust -let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .timeout(Duration::from_secs(120)) - .max_retries(5) - .max_concurrent_requests(50) - .enable_cache(true) - .cache_ttl(Duration::from_secs(600)) - .build()?; -``` - -### SwarmResource - -Resource for swarm-related operations. - -#### Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `completion()` | None | `SwarmCompletionBuilder` | Creates a new swarm completion builder | -| `create(request)` | `SwarmSpec` | `Result` | Creates a swarm completion directly | -| `create_batch(requests)` | `Vec` | `Result, SwarmsError>` | Creates multiple swarm completions | -| `list_types()` | None | `Result` | Lists available swarm types | - -### SwarmCompletionBuilder - -Builder for creating swarm completion requests. - -#### Configuration Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `name(name)` | `String` | `SwarmCompletionBuilder` | Sets the swarm name | -| `description(desc)` | `String` | `SwarmCompletionBuilder` | Sets the swarm description | -| `swarm_type(type)` | `SwarmType` | `SwarmCompletionBuilder` | Sets the swarm type | -| `task(task)` | `String` | `SwarmCompletionBuilder` | Sets the main task | -| `agent(builder_fn)` | `Fn(AgentSpecBuilder) -> AgentSpecBuilder` | `SwarmCompletionBuilder` | Adds an agent using a builder function | -| `max_loops(count)` | `u32` | `SwarmCompletionBuilder` | Sets maximum execution loops | -| `service_tier(tier)` | `String` | `SwarmCompletionBuilder` | Sets the service tier | -| `send()` | None | `Result` | Sends the request | - -### AgentResource - -Resource for agent-related operations. - -#### Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `completion()` | None | `AgentCompletionBuilder` | Creates a new agent completion builder | -| `create(request)` | `AgentCompletion` | `Result` | Creates an agent completion directly | -| `create_batch(requests)` | `Vec` | `Result, SwarmsError>` | Creates multiple agent completions | - -### AgentCompletionBuilder - -Builder for creating agent completion requests. - -#### Configuration Methods - -| Method | Parameters | Returns | Description | -|--------|------------|---------|-------------| -| `agent_name(name)` | `String` | `AgentCompletionBuilder` | Sets the agent name | -| `task(task)` | `String` | `AgentCompletionBuilder` | Sets the task | -| `model(model)` | `String` | `AgentCompletionBuilder` | Sets the AI model | -| `description(desc)` | `String` | `AgentCompletionBuilder` | Sets the agent description | -| `system_prompt(prompt)` | `String` | `AgentCompletionBuilder` | Sets the system prompt | -| `temperature(temp)` | `f32` | `AgentCompletionBuilder` | Sets the temperature (0.0-1.0) | -| `max_tokens(tokens)` | `u32` | `AgentCompletionBuilder` | Sets maximum tokens | -| `max_loops(loops)` | `u32` | `AgentCompletionBuilder` | Sets maximum loops | -| `send()` | None | `Result` | Sends the request | - -### SwarmType Enum - -Available swarm types for different execution patterns. - -| Variant | Description | -|---------|-------------| -| `AgentRearrange` | Agents can be rearranged based on task requirements | -| `MixtureOfAgents` | Combines multiple agents with different specializations | -| `SpreadSheetSwarm` | Organized like a spreadsheet with structured data flow | -| `SequentialWorkflow` | Agents execute in a sequential order | -| `ConcurrentWorkflow` | Agents execute concurrently | -| `GroupChat` | Agents interact in a group chat format | -| `MultiAgentRouter` | Routes tasks between multiple agents | -| `AutoSwarmBuilder` | Automatically builds swarm structure | -| `HiearchicalSwarm` | Hierarchical organization of agents | -| `Auto` | Automatically selects the best swarm type | -| `MajorityVoting` | Agents vote on decisions | -| `Malt` | Multi-Agent Language Tasks | - -## Detailed Examples - -### 1. Simple Agent Completion - -```rust -use swarms_client::{SwarmsClient}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .build()?; - - let response = client.agent() - .completion() - .agent_name("Content Writer") - .task("Write a blog post about sustainable technology") - .model("gpt-4o") - .temperature(0.7) - .max_tokens(2000) - .description("An expert content writer specializing in technology topics") - .system_prompt("You are a professional content writer with expertise in technology and sustainability. Write engaging, informative content that is well-structured and SEO-friendly.") - .send() - .await?; - - println!("Agent Response: {}", response.outputs); - println!("Tokens Used: {}", response.usage.total_tokens); - - Ok(()) -} -``` - -### 2. Multi-Agent Research Swarm - -```rust -use swarms_client::{SwarmsClient, SwarmType}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .timeout(Duration::from_secs(300)) // 5 minutes for complex tasks - .build()?; - - let response = client.swarm() - .completion() - .name("AI Research Swarm") - .description("A comprehensive research team analyzing AI trends and developments") - .swarm_type(SwarmType::SequentialWorkflow) - .task("Conduct a comprehensive analysis of the current state of AI in healthcare, including recent developments, challenges, and future prospects") - - // Data Collection Agent - .agent(|agent| { - agent - .name("Data Collector") - .description("Gathers comprehensive data and recent developments") - .model("gpt-4o") - .system_prompt("You are a research data collector specializing in AI and healthcare. Your job is to gather the most recent and relevant information about AI applications in healthcare, including clinical trials, FDA approvals, and industry developments.") - .temperature(0.3) - .max_tokens(3000) - }) - - // Technical Analyst - .agent(|agent| { - agent - .name("Technical Analyst") - .description("Analyzes technical aspects and implementation details") - .model("gpt-4o") - .system_prompt("You are a technical analyst with deep expertise in AI/ML technologies. Analyze the technical feasibility, implementation challenges, and technological requirements of AI solutions in healthcare.") - .temperature(0.4) - .max_tokens(3000) - }) - - // Market Analyst - .agent(|agent| { - agent - .name("Market Analyst") - .description("Analyzes market trends, adoption rates, and economic factors") - .model("gpt-4o") - .system_prompt("You are a market research analyst specializing in healthcare technology markets. Analyze market size, growth projections, key players, investment trends, and economic factors affecting AI adoption in healthcare.") - .temperature(0.5) - .max_tokens(3000) - }) - - // Regulatory Expert - .agent(|agent| { - agent - .name("Regulatory Expert") - .description("Analyzes regulatory landscape and compliance requirements") - .model("gpt-4o") - .system_prompt("You are a regulatory affairs expert with deep knowledge of healthcare regulations and AI governance. Analyze regulatory challenges, compliance requirements, ethical considerations, and policy developments affecting AI in healthcare.") - .temperature(0.3) - .max_tokens(3000) - }) - - // Report Synthesizer - .agent(|agent| { - agent - .name("Report Synthesizer") - .description("Synthesizes all analyses into a comprehensive report") - .model("gpt-4o") - .system_prompt("You are an expert report writer and strategic analyst. Synthesize all the previous analyses into a comprehensive, well-structured executive report with clear insights, recommendations, and future outlook.") - .temperature(0.6) - .max_tokens(4000) - }) - - .max_loops(1) - .service_tier("premium") - .send() - .await?; - - println!("Research Report:"); - println!("{}", response.output); - println!("\nSwarm executed with {} agents", response.number_of_agents); - - Ok(()) -} -``` - -### 3. Financial Analysis Swarm (From Example) - -```rust -use swarms_client::{SwarmsClient, SwarmType}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .timeout(Duration::from_secs(120)) - .max_retries(3) - .build()?; - - let response = client.swarm() - .completion() - .name("Financial Health Analysis Swarm") - .description("A sequential workflow of specialized financial agents analyzing company health") - .swarm_type(SwarmType::ConcurrentWorkflow) - .task("Analyze the financial health of Apple Inc. (AAPL) based on their latest quarterly report") - - // Financial Data Collector Agent - .agent(|agent| { - agent - .name("Financial Data Collector") - .description("Specializes in gathering and organizing financial data from various sources") - .model("gpt-4o") - .system_prompt("You are a financial data collection specialist. Your role is to gather and organize relevant financial data, including revenue, expenses, profit margins, and key financial ratios. Present the data in a clear, structured format.") - .temperature(0.7) - .max_tokens(2000) - }) - - // Financial Ratio Analyzer Agent - .agent(|agent| { - agent - .name("Ratio Analyzer") - .description("Analyzes key financial ratios and metrics") - .model("gpt-4o") - .system_prompt("You are a financial ratio analysis expert. Your role is to calculate and interpret key financial ratios such as P/E ratio, debt-to-equity, current ratio, and return on equity. Provide insights on what these ratios indicate about the company's financial health.") - .temperature(0.7) - .max_tokens(2000) - }) - - // Additional agents... - .agent(|agent| { - agent - .name("Investment Advisor") - .description("Provides investment recommendations based on analysis") - .model("gpt-4o") - .system_prompt("You are an investment advisory specialist. Your role is to synthesize the analysis from previous agents and provide clear, actionable investment recommendations. Consider both short-term and long-term investment perspectives.") - .temperature(0.7) - .max_tokens(2000) - }) - - .max_loops(1) - .service_tier("standard") - .send() - .await?; - - println!("Financial Analysis Results:"); - println!("{}", response.output); - - Ok(()) -} -``` - -### 4. Batch Processing - -```rust -use swarms_client::{SwarmsClient, AgentCompletion, AgentSpec}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .max_concurrent_requests(20) // Allow more concurrent requests for batch - .build()?; - - // Create multiple agent completion requests - let requests = vec![ - AgentCompletion { - agent_config: AgentSpec { - agent_name: "Content Creator 1".to_string(), - model_name: "gpt-4o-mini".to_string(), - temperature: 0.7, - max_tokens: 1000, - ..Default::default() - }, - task: "Write a social media post about renewable energy".to_string(), - history: None, - }, - AgentCompletion { - agent_config: AgentSpec { - agent_name: "Content Creator 2".to_string(), - model_name: "gpt-4o-mini".to_string(), - temperature: 0.8, - max_tokens: 1000, - ..Default::default() - }, - task: "Write a social media post about electric vehicles".to_string(), - history: None, - }, - // Add more requests... - ]; - - // Process all requests in batch - let responses = client.agent() - .create_batch(requests) - .await?; - - for (i, response) in responses.iter().enumerate() { - println!("Response {}: {}", i + 1, response.outputs); - println!("Tokens used: {}\n", response.usage.total_tokens); - } - - Ok(()) -} -``` - -### 5. Custom Configuration with Error Handling - -```rust -use swarms_client::{SwarmsClient, SwarmsError, ClientConfig}; -use std::time::Duration; - -#[tokio::main] -async fn main() -> Result<(), Box> { - // Custom configuration for production use - let config = ClientConfig { - api_key: std::env::var("SWARMS_API_KEY")?, - base_url: "https://swarms-api-285321057562.us-east1.run.app/".parse()?, - timeout: Duration::from_secs(180), - max_retries: 5, - retry_delay: Duration::from_secs(2), - max_concurrent_requests: 50, - circuit_breaker_threshold: 10, - circuit_breaker_timeout: Duration::from_secs(120), - enable_cache: true, - cache_ttl: Duration::from_secs(600), - }; - - let client = SwarmsClient::with_config(config)?; - - // Example with comprehensive error handling - match client.swarm() - .completion() - .name("Production Swarm") - .swarm_type(SwarmType::Auto) - .task("Analyze market trends for Q4 2024") - .agent(|agent| { - agent - .name("Market Analyst") - .model("gpt-4o") - .temperature(0.5) - }) - .send() - .await - { - Ok(response) => { - println!("Success! Job ID: {}", response.job_id); - println!("Output: {}", response.output); - }, - Err(SwarmsError::Authentication { message, .. }) => { - eprintln!("Authentication error: {}", message); - }, - Err(SwarmsError::RateLimit { message, .. }) => { - eprintln!("Rate limit exceeded: {}", message); - // Implement backoff strategy - }, - Err(SwarmsError::InsufficientCredits { message, .. }) => { - eprintln!("Insufficient credits: {}", message); - }, - Err(SwarmsError::CircuitBreakerOpen) => { - eprintln!("Circuit breaker is open - service temporarily unavailable"); - }, - Err(e) => { - eprintln!("Other error: {}", e); - } - } - - Ok(()) -} -``` - -### 6. Monitoring and Observability - -```rust -use swarms_client::SwarmsClient; -use tracing::{info, warn, error}; - -#[tokio::main] -async fn main() -> Result<(), Box> { - // Initialize tracing for observability - tracing_subscriber::init(); - - let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .enable_cache(true) - .build()?; - - // Monitor cache performance - if let Some((valid, total)) = client.cache_stats() { - info!("Cache stats: {}/{} entries valid", valid, total); - } - - // Make request with monitoring - let start = std::time::Instant::now(); - - let response = client.swarm() - .completion() - .name("Monitored Swarm") - .task("Analyze system performance metrics") - .agent(|agent| { - agent - .name("Performance Analyst") - .model("gpt-4o-mini") - }) - .send() - .await?; - - let duration = start.elapsed(); - info!("Request completed in {:?}", duration); - - if duration > Duration::from_secs(30) { - warn!("Request took longer than expected: {:?}", duration); - } - - // Clear cache periodically in production - client.clear_cache(); - - Ok(()) -} -``` - -## Error Handling - -The client provides comprehensive error handling with specific error types: - -### SwarmsError Types - -| Error Type | Description | Recommended Action | -|------------|-------------|-------------------| -| `Authentication` | Invalid API key or authentication failure | Check API key and permissions | -| `RateLimit` | Rate limit exceeded | Implement exponential backoff | -| `InvalidRequest` | Malformed request parameters | Validate input parameters | -| `InsufficientCredits` | Not enough credits for operation | Check account balance | -| `Api` | General API error | Check API status and retry | -| `Network` | Network connectivity issues | Check internet connection | -| `Timeout` | Request timeout | Increase timeout or retry | -| `CircuitBreakerOpen` | Circuit breaker preventing requests | Wait for recovery period | -| `Serialization` | JSON serialization/deserialization error | Check data format | - -### Error Handling Best Practices - -```rust -use swarms_client::{SwarmsClient, SwarmsError}; - -async fn handle_swarm_request(client: &SwarmsClient, task: &str) -> Result { - match client.swarm() - .completion() - .task(task) - .agent(|agent| agent.name("Worker").model("gpt-4o-mini")) - .send() - .await - { - Ok(response) => Ok(response.output.to_string()), - Err(SwarmsError::RateLimit { .. }) => { - // Implement exponential backoff - tokio::time::sleep(Duration::from_secs(5)).await; - Err(SwarmsError::RateLimit { - message: "Rate limited - should retry".to_string(), - status: Some(429), - request_id: None, - }) - }, - Err(e) => Err(e), - } -} -``` - -## Performance Features - -### Connection Pooling -The client automatically manages HTTP connection pooling for optimal performance: - -```rust -// Connections are automatically pooled and reused -let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .max_concurrent_requests(100) // Allow up to 100 concurrent requests - .build()?; -``` - -### Caching -Intelligent caching reduces redundant API calls: - -```rust -let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .enable_cache(true) - .cache_ttl(Duration::from_secs(300)) // 5-minute TTL - .build()?; - -// GET requests are automatically cached -let models = client.models().list().await?; // First call hits API -let models_cached = client.models().list().await?; // Second call uses cache -``` - -### Circuit Breaker -Automatic failure detection and recovery: - -```rust -let client = SwarmsClient::builder() - .unwrap() - .from_env()? - .build()?; - -// Circuit breaker automatically opens after 5 failures -// and recovers after 60 seconds -``` - -## Configuration Reference - -### ClientConfig Structure - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `api_key` | `String` | `""` | Swarms API key | -| `base_url` | `Url` | `https://swarms-api-285321057562.us-east1.run.app/` | API base URL | -| `timeout` | `Duration` | `60s` | Request timeout | -| `max_retries` | `usize` | `3` | Maximum retry attempts | -| `retry_delay` | `Duration` | `1s` | Base retry delay | -| `max_concurrent_requests` | `usize` | `100` | Concurrent request limit | -| `circuit_breaker_threshold` | `usize` | `5` | Failure threshold for circuit breaker | -| `circuit_breaker_timeout` | `Duration` | `60s` | Circuit breaker recovery time | -| `enable_cache` | `bool` | `true` | Enable response caching | -| `cache_ttl` | `Duration` | `300s` | Cache time-to-live | - -## Environment Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `SWARMS_API_KEY` | Your Swarms API key | `sk-xxx...` | -| `SWARMS_BASE_URL` | Custom API base URL (optional) | `https://api.custom.com/` | - -## Testing - -Run the test suite: - -```bash -cargo test -``` - -Run specific tests: - -```bash -cargo test test_cache -cargo test test_circuit_breaker -``` - -## Contributing - -1. Fork the repository -2. Create a feature branch -3. Add tests for new functionality -4. Ensure all tests pass -5. Submit a pull request - -## License - -This project is licensed under the MIT License - see the LICENSE file for details. \ No newline at end of file diff --git a/docs/swarms_cloud/sequential_workflow.md b/docs/swarms_cloud/sequential_workflow.md deleted file mode 100644 index 1754e6ca..00000000 --- a/docs/swarms_cloud/sequential_workflow.md +++ /dev/null @@ -1,214 +0,0 @@ -# SequentialWorkflow - -*Executes tasks in a strict, predefined order for step-by-step processing* - -**Swarm Type**: `SequentialWorkflow` - -## Overview - -The SequentialWorkflow swarm type executes tasks in a strict, predefined order where each step depends on the completion of the previous one. This architecture is perfect for workflows that require a linear progression of tasks, ensuring that each agent builds upon the work of the previous agent. - -Key features: -- **Ordered Execution**: Agents execute in a specific, predefined sequence -- **Step Dependencies**: Each step builds upon previous results -- **Predictable Flow**: Clear, linear progression through the workflow -- **Quality Control**: Each agent can validate and enhance previous work - -## Use Cases - -- Document processing pipelines -- Multi-stage analysis workflows -- Content creation and editing processes -- Data transformation and validation pipelines - -## API Usage - -### Basic SequentialWorkflow Example - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/swarm/completions" \ - -H "x-api-key: $SWARMS_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Content Creation Pipeline", - "description": "Sequential content creation from research to final output", - "swarm_type": "SequentialWorkflow", - "task": "Create a comprehensive blog post about the future of renewable energy", - "agents": [ - { - "agent_name": "Research Specialist", - "description": "Conducts thorough research on the topic", - "system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Content Writer", - "description": "Creates engaging written content", - "system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.6 - }, - { - "agent_name": "Editor", - "description": "Reviews and polishes the content", - "system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - }, - { - "agent_name": "SEO Optimizer", - "description": "Optimizes content for search engines", - "system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - } - ], - "max_loops": 1 - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "name": "Content Creation Pipeline", - "description": "Sequential content creation from research to final output", - "swarm_type": "SequentialWorkflow", - "task": "Create a comprehensive blog post about the future of renewable energy", - "agents": [ - { - "agent_name": "Research Specialist", - "description": "Conducts thorough research on the topic", - "system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.3 - }, - { - "agent_name": "Content Writer", - "description": "Creates engaging written content", - "system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.6 - }, - { - "agent_name": "Editor", - "description": "Reviews and polishes the content", - "system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.4 - }, - { - "agent_name": "SEO Optimizer", - "description": "Optimizes content for search engines", - "system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.", - "model_name": "gpt-4o", - "max_loops": 1, - "temperature": 0.2 - } - ], - "max_loops": 1 - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("SequentialWorkflow swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - print(f"Final output: {result['output']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -**Example Response**: -```json -{ - "job_id": "swarms-pbM8wqUwxq8afGeROV2A4xAcncd1", - "status": "success", - "swarm_name": "Content Creation Pipeline", - "description": "Sequential content creation from research to final output", - "swarm_type": "SequentialWorkflow", - "output": [ - { - "role": "Research Specialist", - "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we navigate the complexities of the 21st century, the transition to renewable energy stands out as a critical endeavor to ensure a sustainable future......" - }, - { - "role": "SEO Optimizer", - "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nThe transition to renewable energy is crucial as we face the challenges of the 21st century, including climate change and dwindling fossil fuel resources......." - }, - { - "role": "Editor", - "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we confront the challenges of the 21st century, transitioning to renewable energy is essential for a sustainable future. With climate change concerns escalating and fossil fuel reserves depleting, renewable energy is not just an option but a necessity...." - }, - { - "role": "Content Writer", - "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we face the multifaceted challenges of the 21st century, transitioning to renewable energy emerges as not just an option but an essential step toward a sustainable future...." - } - ], - "number_of_agents": 4, - "service_tier": "standard", - "execution_time": 72.23084282875061, - "usage": { - "input_tokens": 28, - "output_tokens": 3012, - "total_tokens": 3040, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.04, - "input_token_cost": 0.000084, - "output_token_cost": 0.04518, - "token_counts": { - "total_input_tokens": 28, - "total_output_tokens": 3012, - "total_tokens": 3040 - }, - "num_agents": 4, - "service_tier": "standard", - "night_time_discount_applied": true - }, - "total_cost": 0.085264, - "discount_active": true, - "discount_type": "night_time", - "discount_percentage": 75 - } - } -} -``` - -## Best Practices - -- Design agents with clear, sequential dependencies -- Ensure each agent builds meaningfully on the previous work -- Use for linear workflows where order matters -- Validate outputs at each step before proceeding - -## Related Swarm Types - -- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel execution -- [AgentRearrange](agent_rearrange.md) - For dynamic sequencing -- [HierarchicalSwarm](hierarchical_swarm.md) - For structured workflows \ No newline at end of file diff --git a/docs/swarms_cloud/subscription_tiers.md b/docs/swarms_cloud/subscription_tiers.md deleted file mode 100644 index 95888056..00000000 --- a/docs/swarms_cloud/subscription_tiers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Swarms Cloud Subscription Tiers - -!!! abstract "Overview" - Choose the perfect plan for your agent infrastructure needs. All plans include our core features with additional benefits as you scale up. - -## Pricing Plans - -### Free Tier - -!!! example "Free" - **$0/year** - - Perfect for getting started with AI development. - - [Get Started](https://swarms.world/platform/account){ .md-button .md-button--primary } - - **What's Included:** - - - [x] Sign up Bonus! - - - [x] Basic Access - - - [x] Pay-Per-Use Pricing - - - [x] Community Support - - - [x] Standard Processing Speed - -### Premium Tier - -!!! success "Premium" - - **Monthly $100/month** - - **Yearly $1,020/year** (Save 15% on annual billing) - - [Subscribe Now](https://swarms.world/platform/account){ .md-button .md-button--primary } - - **Everything in Free, plus:** - - - [x] Full Access to Explorer and Agents - - - [x] Access to Premium Multi-Modality Models - - - [x] Priority Access to Swarms - - - [x] High-Performance Infrastructure - - - [x] Exclusive Webinars and Tutorials - - - [x] Priority Support - - - [x] Enhanced Security Features - - - [x] Early Access to New Models and Features - -### Enterprise Tier - -!!! tip "Enterprise" - **Contact for more Information** - - [Book a Call](https://cal.com/swarms){ .md-button .md-button--primary } - - **Everything in Premium, plus:** - - - [x] High-Performance Infrastructure - - - [x] Batch API - - - [x] Early Access to New Swarms - - - [x] Dedicated 24/7 Support - - - [x] Custom Solutions Engineering - - - [x] Advanced Security Features - - - [x] Onsite Training and Onboarding - - - [x] Custom Model Training - - - [x] Priority Support - - - [x] Pay-Per-Use Pricing - - - [x] Enterprise Telemetry Platform - - - [x] Regular Check-In Strategy Sessions - -## Feature Comparison - -| Feature | Free | Premium | Enterprise | -|---------|------|---------|------------| -| Sign up Bonus | ✅ | ✅ | ✅ | -| Basic Access | ✅ | ✅ | ✅ | -| Pay-Per-Use Pricing | ✅ | ✅ | ✅ | -| Community Support | ✅ | ✅ | ✅ | -| Standard Processing Speed | ✅ | ✅ | ✅ | -| Full Access to Explorer and Agents | ❌ | ✅ | ✅ | -| Premium Multi-Modality Models | ❌ | ✅ | ✅ | -| Priority Access to Swarms | ❌ | ✅ | ✅ | -| High-Performance GPUs | ❌ | ✅ | ✅ | -| Exclusive Webinars and Tutorials | ❌ | ✅ | ✅ | -| Priority Support | ❌ | ✅ | ✅ | -| Enhanced Security Features | ❌ | ✅ | ✅ | -| Early Access to New Models | ❌ | ✅ | ✅ | -| Batch API | ❌ | ❌ | ✅ | -| Dedicated 24/7 Support | ❌ | ❌ | ✅ | -| Custom Solutions Engineering | ❌ | ❌ | ✅ | -| Onsite Training and Onboarding | ❌ | ❌ | ✅ | -| Custom Model Training | ❌ | ❌ | ✅ | - -## Rate Limits - -!!! info "Rate Limit Increases" - - **Premium**: 100% increase in rate limits - - **Enterprise**: Custom rate limits based on your needs (contact us for details) - -## Getting Started - -1. Choose your plan -2. Create your account -3. Start building with Swarms! - -!!! success "Need Help?" - - For general questions: [Contact Support](mailto:kye@swarms.world) - - For enterprise inquiries: [Book a Call](https://cal.com/swarms) - - Upgrade Your Membership: [Upgrade Now](https://swarms.world/platform/account) diff --git a/docs/swarms_cloud/swarm_types.md b/docs/swarms_cloud/swarm_types.md deleted file mode 100644 index 5773237b..00000000 --- a/docs/swarms_cloud/swarm_types.md +++ /dev/null @@ -1,28 +0,0 @@ -# Multi-Agent Architectures - -Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Below is an overview of each available swarm type: - -| Swarm Type | Description | Learn More | -|----------------------|------------------------------------------------------------------------------|------------| -| AgentRearrange | Dynamically reorganizes agents to optimize task performance and efficiency. Useful when agent effectiveness depends on their sequence or arrangement. | [Learn More](agent_rearrange.md) | -| MixtureOfAgents | Builds diverse teams of specialized agents, each contributing unique skills to solve complex problems. Excels at tasks requiring multiple types of expertise. | [Learn More](mixture_of_agents.md) | -| SequentialWorkflow | Executes tasks in a strict, predefined order. Perfect for workflows where each step depends on the completion of the previous one. | [Learn More](sequential_workflow.md) | -| ConcurrentWorkflow | Runs independent tasks in parallel, significantly reducing processing time for complex operations. Ideal for tasks that can be processed simultaneously. | [Learn More](concurrent_workflow.md) | -| GroupChat | Enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. | [Learn More](group_chat.md) | -| HierarchicalSwarm | Implements a structured, multi-level approach to task management, with clear lines of authority and delegation. | [Learn More](hierarchical_swarm.md) | -| MultiAgentRouter | Acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. | [Learn More](multi_agent_router.md) | -| MajorityVoting | Implements robust decision-making through consensus, ideal for tasks requiring collective intelligence or verification. | [Learn More](majority_voting.md) | - - - - - -# Learn More - -To explore Swarms architecture and how different swarm types work together, check out our comprehensive guides: - -- [Introduction to Multi-Agent Architectures](/swarms/concept/swarm_architectures) -- [How to Choose the Right Multi-Agent Architecture](/swarms/concept/how_to_choose_swarms) -- [Framework Architecture Overview](/swarms/concept/framework_architecture) -- [Building Custom Swarms](/swarms/structs/custom_swarm) diff --git a/docs/swarms_cloud/swarms_api.md b/docs/swarms_cloud/swarms_api.md deleted file mode 100644 index 8dd7aba3..00000000 --- a/docs/swarms_cloud/swarms_api.md +++ /dev/null @@ -1,1271 +0,0 @@ -# Swarms API Documentation - -*Enterprise-Grade Agent Swarm Management API* - -**Base URL**: `https://api.swarms.world` or `https://swarms-api-285321057562.us-east1.run.app` - -**API Key Management**: [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys) - -## Overview - -The Swarms API provides a robust, scalable infrastructure for deploying and managing intelligent agent swarms in the cloud. This enterprise-grade API enables organizations to create, execute, and orchestrate sophisticated AI agent workflows without managing the underlying infrastructure. - -Key capabilities include: - -- **Intelligent Swarm Management**: Create and execute swarms of specialized AI agents that collaborate to solve complex tasks - -- **Automatic Agent Generation**: Dynamically create optimized agents based on task requirements - -- **Multiple Swarm Architectures**: Choose from various swarm patterns to match your specific workflow needs - -- **Comprehensive Logging**: Track and analyze all API interactions - -- **Cost Management**: Predictable, transparent pricing with optimized resource utilization - -- **Enterprise Security**: Full API key authentication and management - -Swarms API is designed for production use cases requiring sophisticated AI orchestration, with applications in finance, healthcare, legal, research, and other domains where complex reasoning and multi-agent collaboration are needed. - -## Authentication - -All API requests require a valid API key, which must be included in the header of each request: - -``` -x-api-key: your_api_key_here -``` - -API keys can be obtained and managed at [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys). - -## API Reference - -### Endpoints Summary - -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/health` | GET | Simple health check endpoint | -| `/v1/swarm/completions` | POST | Run a swarm with specified configuration | -| `/v1/swarm/batch/completions` | POST | Run multiple swarms in batch mode | -| `/v1/swarm/logs` | GET | Retrieve API request logs | -| `/v1/swarms/available` | GET | Get all available swarms as a list of strings | -| `/v1/models/available` | GET | Get all available models as a list of strings | -| `/v1/agent/completions` | POST | Run a single agent with specified configuration | -| `/v1/agent/batch/completions` | POST | Run a batch of individual agent completions| - - - -### SwarmType Reference - -The `swarm_type` parameter defines the architecture and collaboration pattern of the agent swarm: - -| SwarmType | Description | -|-----------|-------------| -| `AgentRearrange` | Dynamically reorganizes the workflow between agents based on task requirements | -| `MixtureOfAgents` | Combines multiple agent types to tackle diverse aspects of a problem | -| `SpreadSheetSwarm` | Specialized for spreadsheet data analysis and manipulation | -| `SequentialWorkflow` | Agents work in a predefined sequence, each handling specific subtasks | -| `ConcurrentWorkflow` | Multiple agents work simultaneously on different aspects of the task | -| `GroupChat` | Agents collaborate in a discussion format to solve problems | -| `MultiAgentRouter` | Routes subtasks to specialized agents based on their capabilities | -| `AutoSwarmBuilder` | Automatically designs and builds an optimal swarm based on the task | -| `HiearchicalSwarm` | Organizes agents in a hierarchical structure with managers and workers | -| `MajorityVoting` | Uses a consensus mechanism where multiple agents vote on the best solution | -| `auto` | Automatically selects the most appropriate swarm type for the given task | - - - -## Data Models - -### SwarmSpec - -The `SwarmSpec` model defines the configuration of a swarm. - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| name | string | Identifier for the swarm | No | -| description | string | Description of the swarm's purpose | No | -| agents | Array | List of agent specifications | No | -| max_loops | integer | Maximum number of execution loops | No | -| swarm_type | SwarmType | Architecture of the swarm | No | -| rearrange_flow | string | Instructions for rearranging task flow | No | -| task | string | The main task for the swarm to accomplish | Yes | -| img | string | Optional image URL for the swarm | No | -| return_history | boolean | Whether to return execution history | No | -| rules | string | Guidelines for swarm behavior | No | -| service_tier | string | Service tier for processing ("standard" or "flex") | No | - -### AgentSpec - -The `AgentSpec` model defines the configuration of an individual agent. - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| agent_name | string | Unique name for the agent | Yes* | -| description | string | Description of the agent's purpose | No | -| system_prompt | string | Instructions for the agent | No | -| model_name | string | AI model to use (e.g., "gpt-4o") | Yes* | -| auto_generate_prompt | boolean | Whether to auto-generate prompts | No | -| max_tokens | integer | Maximum tokens in response | No | -| temperature | float | Randomness of responses (0-1) | No | -| role | string | Agent's role in the swarm | No | -| max_loops | integer | Maximum iterations for this agent | No | - -*Required if agents are manually specified; not required if using auto-generated agents - - -### Endpoint Details - -#### Health Check - -Check if the API service is available and functioning correctly. - -**Endpoint**: `/health` -**Method**: GET -**Rate Limit**: 100 requests per 60 seconds - -=== "Shell (curl)" - ```bash - curl -X GET "https://api.swarms.world/health" \ - -H "x-api-key: your_api_key_here" - ``` - -=== "Python (requests)" - ```python - import requests - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY - } - - response = requests.get(f"{API_BASE_URL}/health", headers=headers) - - if response.status_code == 200: - print("API is healthy:", response.json()) - else: - print(f"Error: {response.status_code}") - ``` - -=== "TypeScript (fetch)" - ```typescript - const API_BASE_URL = "https://api.swarms.world"; - const API_KEY = "your_api_key_here"; - - async function checkHealth(): Promise { - try { - const response = await fetch(`${API_BASE_URL}/health`, { - method: 'GET', - headers: { - 'x-api-key': API_KEY - } - }); - - if (response.ok) { - const data = await response.json(); - console.log("API is healthy:", data); - } else { - console.error(`Error: ${response.status}`); - } - } catch (error) { - console.error("Request failed:", error); - } - } - - checkHealth(); - ``` - -**Example Response**: -```json -{ - "status": "ok" -} -``` - -#### Run Swarm - -Run a swarm with the specified configuration to complete a task. - -**Endpoint**: `/v1/swarm/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds - -**Request Parameters**: - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| name | string | Identifier for the swarm | No | -| description | string | Description of the swarm's purpose | No | -| agents | Array | List of agent specifications | No | -| max_loops | integer | Maximum number of execution loops | No | -| swarm_type | SwarmType | Architecture of the swarm | No | -| rearrange_flow | string | Instructions for rearranging task flow | No | -| task | string | The main task for the swarm to accomplish | Yes | -| img | string | Optional image URL for the swarm | No | -| return_history | boolean | Whether to return execution history | No | -| rules | string | Guidelines for swarm behavior | No | - -=== "Shell (curl)" - ```bash - 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": "openai/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": "ConcurrentWorkflow", - "task": "What are the best etfs and index funds for ai and tech?", - "output_type": "dict" - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - swarm_config = { - "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": "openai/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": "ConcurrentWorkflow", - "task": "What are the best etfs and index funds for ai and tech?", - "output_type": "dict" - } - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/completions", - headers=headers, - json=swarm_config - ) - - if response.status_code == 200: - result = response.json() - print("Swarm completed successfully!") - print(f"Cost: ${result['metadata']['billing_info']['total_cost']}") - print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -=== "TypeScript (fetch)" - ```typescript - interface AgentSpec { - 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 SwarmConfig { - name: string; - description: string; - agents: AgentSpec[]; - max_loops: number; - swarm_type: string; - task: string; - output_type: string; - } - - const API_BASE_URL = "https://api.swarms.world"; - const API_KEY = "your_api_key_here"; - - async function runSwarm(): Promise { - const swarmConfig: SwarmConfig = { - 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: "openai/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: "ConcurrentWorkflow", - task: "What are the best etfs and index funds for ai and tech?", - output_type: "dict" - }; - - try { - const response = await fetch(`${API_BASE_URL}/v1/swarm/completions`, { - method: 'POST', - headers: { - 'x-api-key': API_KEY, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(swarmConfig) - }); - - if (response.ok) { - const result = await response.json(); - console.log("Swarm completed successfully!"); - console.log(`Cost: $${result.metadata.billing_info.total_cost}`); - console.log(`Execution time: ${result.metadata.execution_time_seconds} seconds`); - } else { - console.error(`Error: ${response.status} - ${await response.text()}`); - } - } catch (error) { - console.error("Request failed:", error); - } - } - - runSwarm(); - ``` - -**Example Response**: -```json -{ - "status": "success", - "swarm_name": "financial-analysis-swarm", - "description": "Analyzes financial data for risk assessment", - "swarm_type": "SequentialWorkflow", - "task": "Analyze the provided quarterly financials for Company XYZ and identify potential risk factors. Summarize key insights and provide recommendations for risk mitigation.", - "output": { - "financial_analysis": { - "risk_factors": [...], - "key_insights": [...], - "recommendations": [...] - } - }, - "metadata": { - "max_loops": 2, - "num_agents": 3, - "execution_time_seconds": 12.45, - "completion_time": 1709563245.789, - "billing_info": { - "cost_breakdown": { - "agent_cost": 0.03, - "input_token_cost": 0.002134, - "output_token_cost": 0.006789, - "token_counts": { - "total_input_tokens": 1578, - "total_output_tokens": 3456, - "total_tokens": 5034, - "per_agent": {...} - }, - "num_agents": 3, - "execution_time_seconds": 12.45 - }, - "total_cost": 0.038923 - } - } -} -``` - -#### Run Batch Completions - -Run multiple swarms as a batch operation. - -**Endpoint**: `/v1/swarm/batch/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds - -**Request Parameters**: - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| swarms | Array | List of swarm specifications | Yes | - -=== "Shell (curl)" - ```bash - 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 the batch", - "agents": [ - { - "agent_name": "Research Agent", - "description": "Conducts research", - "system_prompt": "You are a research assistant.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Analysis Agent", - "description": "Analyzes data", - "system_prompt": "You are a data analyst.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Research AI advancements." - }, - { - "name": "Batch Swarm 2", - "description": "Second swarm in the batch", - "agents": [ - { - "agent_name": "Writing Agent", - "description": "Writes content", - "system_prompt": "You are a content writer.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Editing Agent", - "description": "Edits content", - "system_prompt": "You are an editor.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Write a summary of AI research." - } - ]' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - batch_swarms = [ - { - "name": "Batch Swarm 1", - "description": "First swarm in the batch", - "agents": [ - { - "agent_name": "Research Agent", - "description": "Conducts research", - "system_prompt": "You are a research assistant.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Analysis Agent", - "description": "Analyzes data", - "system_prompt": "You are a data analyst.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Research AI advancements." - }, - { - "name": "Batch Swarm 2", - "description": "Second swarm in the batch", - "agents": [ - { - "agent_name": "Writing Agent", - "description": "Writes content", - "system_prompt": "You are a content writer.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - }, - { - "agent_name": "Editing Agent", - "description": "Edits content", - "system_prompt": "You are an editor.", - "model_name": "gpt-4o", - "role": "worker", - "max_loops": 1 - } - ], - "max_loops": 1, - "swarm_type": "SequentialWorkflow", - "task": "Write a summary of AI research." - } - ] - - response = requests.post( - f"{API_BASE_URL}/v1/swarm/batch/completions", - headers=headers, - json=batch_swarms - ) - - if response.status_code == 200: - results = response.json() - print(f"Batch completed with {len(results)} swarms") - for i, result in enumerate(results): - print(f"Swarm {i+1}: {result['swarm_name']} - {result['status']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -=== "TypeScript (fetch)" - ```typescript - interface AgentSpec { - agent_name: string; - description: string; - system_prompt: string; - model_name: string; - role: string; - max_loops: number; - } - - interface SwarmSpec { - name: string; - description: string; - agents: AgentSpec[]; - max_loops: number; - swarm_type: string; - task: string; - } - - const API_BASE_URL = "https://api.swarms.world"; - const API_KEY = "your_api_key_here"; - - async function runBatchSwarms(): Promise { - const batchSwarms: SwarmSpec[] = [ - { - name: "Batch Swarm 1", - description: "First swarm in the batch", - agents: [ - { - agent_name: "Research Agent", - description: "Conducts research", - system_prompt: "You are a research assistant.", - model_name: "gpt-4o", - role: "worker", - max_loops: 1 - }, - { - agent_name: "Analysis Agent", - description: "Analyzes data", - system_prompt: "You are a data analyst.", - model_name: "gpt-4o", - role: "worker", - max_loops: 1 - } - ], - max_loops: 1, - swarm_type: "SequentialWorkflow", - task: "Research AI advancements." - }, - { - name: "Batch Swarm 2", - description: "Second swarm in the batch", - agents: [ - { - agent_name: "Writing Agent", - description: "Writes content", - system_prompt: "You are a content writer.", - model_name: "gpt-4o", - role: "worker", - max_loops: 1 - }, - { - agent_name: "Editing Agent", - description: "Edits content", - system_prompt: "You are an editor.", - model_name: "gpt-4o", - role: "worker", - max_loops: 1 - } - ], - max_loops: 1, - swarm_type: "SequentialWorkflow", - task: "Write a summary of AI research." - } - ]; - - try { - const response = await fetch(`${API_BASE_URL}/v1/swarm/batch/completions`, { - method: 'POST', - headers: { - 'x-api-key': API_KEY, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(batchSwarms) - }); - - if (response.ok) { - const results = await response.json(); - console.log(`Batch completed with ${results.length} swarms`); - results.forEach((result: any, index: number) => { - console.log(`Swarm ${index + 1}: ${result.swarm_name} - ${result.status}`); - }); - } else { - console.error(`Error: ${response.status} - ${await response.text()}`); - } - } catch (error) { - console.error("Request failed:", error); - } - } - - runBatchSwarms(); - ``` - -**Example Response**: -```json -[ - { - "status": "success", - "swarm_name": "risk-analysis", - "task": "Analyze risk factors for investment portfolio", - "output": {...}, - "metadata": {...} - }, - { - "status": "success", - "swarm_name": "market-sentiment", - "task": "Assess current market sentiment for technology sector", - "output": {...}, - "metadata": {...} - } -] -``` - -## Individual Agent Endpoints - -### Run Single Agent - -Run a single agent with the specified configuration. - -**Endpoint**: `/v1/agent/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds - -**Request Parameters**: - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| agent_config | AgentSpec | Configuration for the agent | Yes | -| task | string | The task to be completed by the agent | Yes | - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/agent/completions" \ - -H "x-api-key: your_api_key_here" \ - -H "Content-Type: application/json" \ - -d '{ - "agent_config": { - "agent_name": "Research Assistant", - "description": "Helps with research tasks", - "system_prompt": "You are a research assistant expert.", - "model_name": "gpt-4o", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5 - }, - "task": "Research the latest developments in quantum computing." - }' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - agent_request = { - "agent_config": { - "agent_name": "Research Assistant", - "description": "Helps with research tasks", - "system_prompt": "You are a research assistant expert.", - "model_name": "gpt-4o", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5 - }, - "task": "Research the latest developments in quantum computing." - } - - response = requests.post( - f"{API_BASE_URL}/v1/agent/completions", - headers=headers, - json=agent_request - ) - - if response.status_code == 200: - result = response.json() - print(f"Agent {result['name']} completed successfully!") - print(f"Usage: {result['usage']['total_tokens']} tokens") - print(f"Output: {result['outputs']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -=== "TypeScript (fetch)" - ```typescript - interface AgentConfig { - agent_name: string; - description: string; - system_prompt: string; - model_name: string; - max_loops: number; - max_tokens: number; - temperature: number; - } - - interface AgentRequest { - agent_config: AgentConfig; - task: string; - } - - const API_BASE_URL = "https://api.swarms.world"; - const API_KEY = "your_api_key_here"; - - async function runSingleAgent(): Promise { - const agentRequest: AgentRequest = { - agent_config: { - agent_name: "Research Assistant", - description: "Helps with research tasks", - system_prompt: "You are a research assistant expert.", - model_name: "gpt-4o", - max_loops: 1, - max_tokens: 8192, - temperature: 0.5 - }, - task: "Research the latest developments in quantum computing." - }; - - try { - const response = await fetch(`${API_BASE_URL}/v1/agent/completions`, { - method: 'POST', - headers: { - 'x-api-key': API_KEY, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(agentRequest) - }); - - if (response.ok) { - const result = await response.json(); - console.log(`Agent ${result.name} completed successfully!`); - console.log(`Usage: ${result.usage.total_tokens} tokens`); - console.log(`Output:`, result.outputs); - } else { - console.error(`Error: ${response.status} - ${await response.text()}`); - } - } catch (error) { - console.error("Request failed:", error); - } - } - - runSingleAgent(); - ``` - -**Example Response**: -```json -{ - "id": "agent-abc123", - "success": true, - "name": "Research Assistant", - "description": "Helps with research tasks", - "temperature": 0.5, - "outputs": {}, - "usage": { - "input_tokens": 150, - "output_tokens": 450, - "total_tokens": 600 - }, - "timestamp": "2024-03-05T12:34:56.789Z" -} -``` - -### AgentCompletion Model - -The `AgentCompletion` model defines the configuration for running a single agent task. - -| Field | Type | Description | Required | -|-------|------|-------------|----------| -| `agent_config` | AgentSpec | The configuration of the agent to be completed | Yes | -| `task` | string | The task to be completed by the agent | Yes | -| `history` | Dict[str, Any] | The history of the agent's previous tasks and responses | No | - - -### AgentSpec Model - -The `AgentSpec` model defines the configuration for an individual agent. - -| Field | Type | Default | Description | Required | -|-------|------|---------|-------------|----------| -| `agent_name` | string | None | The unique name assigned to the agent | Yes | -| `description` | string | None | Detailed explanation of the agent's purpose | No | -| `system_prompt` | string | None | Initial instruction provided to the agent | No | -| `model_name` | string | "gpt-4o-mini" | Name of the AI model to use | No | -| `auto_generate_prompt` | boolean | false | Whether to auto-generate prompts | No | -| `max_tokens` | integer | 8192 | Maximum tokens in response | No | -| `temperature` | float | 0.5 | Controls randomness (0-1) | No | -| `role` | string | "worker" | Role of the agent | No | -| `max_loops` | integer | 1 | Maximum iterations | No | -| `tools_list_dictionary` | List[Dict] | None | Available tools for the agent | No | -| `mcp_url` | string | None | URL for Model Control Protocol | No | - - -Execute a task using a single agent with specified configuration. - -**Endpoint**: `/v1/agent/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds - -**Request Body**: -```json -{ - "agent_config": { - "agent_name": "Research Assistant", - "description": "Specialized in research and analysis", - "system_prompt": "You are an expert research assistant.", - "model_name": "gpt-4o", - "auto_generate_prompt": false, - "max_tokens": 8192, - "temperature": 0.5, - "role": "worker", - "max_loops": 1, - "tools_list_dictionary": [ - { - "name": "search", - "description": "Search the web for information", - "parameters": { - "query": "string" - } - } - ], - "mcp_url": "https://example-mcp.com" - }, - "task": "Research the latest developments in quantum computing and summarize key findings", - "history": { - "previous_research": "Earlier findings on quantum computing basics...", - "user_preferences": "Focus on practical applications..." - } -} -``` - -**Response**: -```json -{ - "id": "agent-abc123xyz", - "success": true, - "name": "Research Assistant", - "description": "Specialized in research and analysis", - "temperature": 0.5, - "outputs": { - "research_summary": "...", - "key_findings": [ - "..." - ] - }, - "usage": { - "input_tokens": 450, - "output_tokens": 850, - "total_tokens": 1300, - "mcp_url": 0.1 - }, - "timestamp": "2024-03-05T12:34:56.789Z" -} -``` - -#### Run Batch Agents - -Execute multiple agent tasks in parallel. - -**Endpoint**: `/v1/agent/batch/completions` -**Method**: POST -**Rate Limit**: 100 requests per 60 seconds -**Maximum Batch Size**: 10 requests -**Input** A list of `AgentCompeletion` inputs - -=== "Shell (curl)" - ```bash - curl -X POST "https://api.swarms.world/v1/agent/batch/completions" \ - -H "x-api-key: your_api_key_here" \ - -H "Content-Type: application/json" \ - -d '[ - { - "agent_config": { - "agent_name": "Market Analyst", - "description": "Expert in market analysis", - "system_prompt": "You are a financial market analyst.", - "model_name": "gpt-4o", - "temperature": 0.3 - }, - "task": "Analyze the current market trends in AI technology sector" - }, - { - "agent_config": { - "agent_name": "Technical Writer", - "description": "Specialized in technical documentation", - "system_prompt": "You are a technical documentation expert.", - "model_name": "gpt-4o", - "temperature": 0.7 - }, - "task": "Create a technical guide for implementing OAuth2 authentication" - } - ]' - ``` - -=== "Python (requests)" - ```python - import requests - import json - - API_BASE_URL = "https://api.swarms.world" - API_KEY = "your_api_key_here" - - headers = { - "x-api-key": API_KEY, - "Content-Type": "application/json" - } - - batch_agents = [ - { - "agent_config": { - "agent_name": "Market Analyst", - "description": "Expert in market analysis", - "system_prompt": "You are a financial market analyst.", - "model_name": "gpt-4o", - "temperature": 0.3 - }, - "task": "Analyze the current market trends in AI technology sector" - }, - { - "agent_config": { - "agent_name": "Technical Writer", - "description": "Specialized in technical documentation", - "system_prompt": "You are a technical documentation expert.", - "model_name": "gpt-4o", - "temperature": 0.7 - }, - "task": "Create a technical guide for implementing OAuth2 authentication" - } - ] - - response = requests.post( - f"{API_BASE_URL}/v1/agent/batch/completions", - headers=headers, - json=batch_agents - ) - - if response.status_code == 200: - result = response.json() - print(f"Batch completed with {result['total_requests']} agents") - print(f"Execution time: {result['execution_time']} seconds") - print("\nResults:") - for i, agent_result in enumerate(result['results']): - print(f" Agent {i+1}: {agent_result['name']} - {agent_result['success']}") - else: - print(f"Error: {response.status_code} - {response.text}") - ``` - -=== "TypeScript (fetch)" - ```typescript - interface AgentConfig { - agent_name: string; - description: string; - system_prompt: string; - model_name: string; - temperature: number; - } - - interface AgentCompletion { - agent_config: AgentConfig; - task: string; - } - - const API_BASE_URL = "https://api.swarms.world"; - const API_KEY = "your_api_key_here"; - - async function runBatchAgents(): Promise { - const batchAgents: AgentCompletion[] = [ - { - agent_config: { - agent_name: "Market Analyst", - description: "Expert in market analysis", - system_prompt: "You are a financial market analyst.", - model_name: "gpt-4o", - temperature: 0.3 - }, - task: "Analyze the current market trends in AI technology sector" - }, - { - agent_config: { - agent_name: "Technical Writer", - description: "Specialized in technical documentation", - system_prompt: "You are a technical documentation expert.", - model_name: "gpt-4o", - temperature: 0.7 - }, - task: "Create a technical guide for implementing OAuth2 authentication" - } - ]; - - try { - const response = await fetch(`${API_BASE_URL}/v1/agent/batch/completions`, { - method: 'POST', - headers: { - 'x-api-key': API_KEY, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(batchAgents) - }); - - if (response.ok) { - const result = await response.json(); - console.log(`Batch completed with ${result.total_requests} agents`); - console.log(`Execution time: ${result.execution_time} seconds`); - console.log("\nResults:"); - result.results.forEach((agentResult: any, index: number) => { - console.log(` Agent ${index + 1}: ${agentResult.name} - ${agentResult.success}`); - }); - } else { - console.error(`Error: ${response.status} - ${await response.text()}`); - } - } catch (error) { - console.error("Request failed:", error); - } - } - - runBatchAgents(); - ``` - -**Response**: -```json -{ - "batch_id": "agent-batch-xyz789", - "total_requests": 2, - "execution_time": 15.5, - "timestamp": "2024-03-05T12:34:56.789Z", - "results": [ - { - "id": "agent-abc123", - "success": true, - "name": "Market Analyst", - "outputs": { - "market_analysis": "..." - }, - "usage": { - "input_tokens": 300, - "output_tokens": 600, - "total_tokens": 900 - } - }, - { - "id": "agent-def456", - "success": true, - "name": "Technical Writer", - "outputs": { - "technical_guide": "..." - }, - "usage": { - "input_tokens": 400, - "output_tokens": 800, - "total_tokens": 1200 - } - } - ] -} -``` - ------ - -## Production Examples - -## Error Handling - -The Swarms API follows standard HTTP status codes for error responses: - -| Status Code | Meaning | Handling Strategy | -|-------------|---------|-------------------| -| 400 | Bad Request | Validate request parameters before sending | -| 401 | Unauthorized | Check API key validity | -| 403 | Forbidden | Verify API key permissions | -| 404 | Not Found | Check endpoint URL and resource IDs | -| 429 | Too Many Requests | Implement exponential backoff retry logic | -| 500 | Internal Server Error | Retry with backoff, then contact support | - -Error responses include a detailed message explaining the issue: - -```json -{ - "detail": "Failed to create swarm: Invalid swarm_type specified" -} -``` - -## Rate Limiting - -| Description | Details | -|-------------|---------| -| Rate Limit | 100 requests per 60-second window | -| Exceed Consequence | 429 status code returned | -| Recommended Action | Implement retry logic with exponential backoff | - -## Billing & Cost Management - -| Cost Factor | Description | -|-------------|-------------| -| Agent Count | Base cost per agent | -| Input Tokens | Cost based on size of input data and prompts | -| Output Tokens | Cost based on length of generated responses | -| Time of Day | Reduced rates during nighttime hours (8 PM to 6 AM PT) | -| Cost Information | Included in each response's metadata | - -## Best Practices - -### Task Description - -| Practice | Description | -|----------|-------------| -| Detail | Provide detailed, specific task descriptions | -| Context | Include all necessary context and constraints | -| Structure | Structure complex inputs for easier processing | - -### Agent Configuration - -| Practice | Description | -|----------|-------------| -| Simple Tasks | Use `AutoSwarmBuilder` for automatic agent generation | -| Complex Tasks | Manually define agents with specific expertise | -| Workflow | Use appropriate `swarm_type` for your workflow pattern | - -### Production Implementation - -| Practice | Description | -|----------|-------------| -| Error Handling | Implement robust error handling and retries | -| Logging | Log API responses for debugging and auditing | -| Cost Monitoring | Monitor costs closely during development and testing | - -### Cost Optimization - -| Practice | Description | -|----------|-------------| -| Batching | Batch related tasks when possible | -| Scheduling | Schedule non-urgent tasks during discount hours | -| Scoping | Carefully scope task descriptions to reduce token usage | -| Caching | Cache results when appropriate | - -## Support - -| Support Type | Contact Information | -|--------------|---------------------| -| Documentation | [https://docs.swarms.world](https://docs.swarms.world) | -| Email | kye@swarms.world | -| Community | [https://discord.gg/EamjgSaEQf](https://discord.gg/EamjgSaEQf) | -| Marketplace | [https://swarms.world](https://swarms.world) | -| Website | [https://swarms.ai](https://swarms.ai) | - -## Service Tiers - -### Standard Tier - -| Feature | Description | -|---------|-------------| -| Processing | Default processing tier | -| Execution | Immediate execution | -| Priority | Higher priority processing | -| Pricing | Standard pricing | -| Timeout | 5-minute timeout limit | - -### Flex Tier - -| Feature | Description | -|---------|-------------| -| Cost | Lower cost processing | -| Retries | Automatic retries (up to 3 attempts) | -| Timeout | 15-minute timeout | -| Discount | 75% discount on token costs | -| Suitability | Best for non-urgent tasks | -| Backoff | Exponential backoff on resource contention | -| Configuration | Set `service_tier: "flex"` in SwarmSpec | \ No newline at end of file diff --git a/docs/swarms_cloud/swarms_api_tools.md b/docs/swarms_cloud/swarms_api_tools.md deleted file mode 100644 index 61cf1742..00000000 --- a/docs/swarms_cloud/swarms_api_tools.md +++ /dev/null @@ -1,382 +0,0 @@ -# Swarms API with Tools Guide - - -Swarms API allows you to create and manage AI agent swarms with optional tool integration. This guide will walk you through setting up and using the Swarms API with tools. - -## Prerequisites - -- Python 3.7+ -- Swarms API key -- Required Python packages: - - `requests` - - - `python-dotenv` - -## Installation & Setup - -1. Install required packages: - -```bash -pip install requests python-dotenv -``` - -2. Create a `.env` file in your project root: - -```bash -SWARMS_API_KEY=your_api_key_here -``` - -3. Basic setup code: - -```python -import os -import requests -from dotenv import load_dotenv -import json - -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"} -``` - -## Creating a Swarm with Tools - -### Step-by-Step Guide - -1. Define your tool dictionary: -```python -tool_dictionary = { - "type": "function", - "function": { - "name": "search_topic", - "description": "Conduct an in-depth search on a specified topic", - "parameters": { - "type": "object", - "properties": { - "depth": { - "type": "integer", - "description": "Search depth (1-3)" - }, - "detailed_queries": { - "type": "array", - "items": { - "type": "string", - "description": "Specific search queries" - } - } - }, - "required": ["depth", "detailed_queries"] - } - } -} -``` - -2. Create agent configurations: -```python -agent_config = { - "agent_name": "Market Analyst", - "description": "Analyzes market trends", - "system_prompt": "You are a financial analyst expert.", - "model_name": "openai/gpt-4", - "role": "worker", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": False, - "tools_dictionary": [tool_dictionary] # Optional: Add tools if needed -} -``` - -3. Create the swarm payload: -```python -payload = { - "name": "Your Swarm Name", - "description": "Swarm description", - "agents": [agent_config], - "max_loops": 1, - "swarm_type": "ConcurrentWorkflow", - "task": "Your task description", - "output_type": "dict" -} -``` - -4. Make the API request: -```python -def run_swarm(payload): - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload - ) - return response.json() -``` - -## FAQ - -### Do all agents need tools? -No, tools are optional for each agent. You can choose which agents have tools based on your specific needs. Simply omit the `tools_dictionary` field for agents that don't require tools. - -### What types of tools can I use? -Currently, the API supports function-type tools. Each tool must have: -- A unique name - -- A clear description - -- Well-defined parameters with types and descriptions - -### Can I mix agents with and without tools? -Yes, you can create swarms with a mix of tool-enabled and regular agents. This allows for flexible swarm architectures. - -### What's the recommended number of tools per agent? -While there's no strict limit, it's recommended to: - -- Keep tools focused and specific - -- Only include tools that the agent needs - -- Consider the complexity of tool interactions - -## Example Implementation - -Here's a complete example of a financial analysis swarm: - -```python -def run_financial_analysis_swarm(): - payload = { - "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": "openai/gpt-4", - "role": "worker", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": False, - "tools_dictionary": [ - { - "type": "function", - "function": { - "name": "search_topic", - "description": "Conduct market research", - "parameters": { - "type": "object", - "properties": { - "depth": { - "type": "integer", - "description": "Search depth (1-3)" - }, - "detailed_queries": { - "type": "array", - "items": {"type": "string"} - } - }, - "required": ["depth", "detailed_queries"] - } - } - } - ] - } - ], - "max_loops": 1, - "swarm_type": "ConcurrentWorkflow", - "task": "Analyze top performing tech ETFs", - "output_type": "dict" - } - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload - ) - return response.json() -``` - -## Health Check - -Always verify the API status before running swarms: - -```python -def check_api_health(): - response = requests.get(f"{BASE_URL}/health", headers=headers) - return response.json() -``` - -## Best Practices - -1. **Error Handling**: Always implement proper error handling: -```python -def safe_run_swarm(payload): - try: - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload - ) - response.raise_for_status() - return response.json() - except requests.exceptions.RequestException as e: - print(f"Error running swarm: {e}") - return None -``` - -2. **Environment Variables**: Never hardcode API keys - -3. **Tool Design**: Keep tools simple and focused - -4. **Testing**: Validate swarm configurations before production use - -## Troubleshooting - -Common issues and solutions: - -1. **API Key Issues** - - Verify key is correctly set in `.env` - - - Check key permissions - -2. **Tool Execution Errors** - - Validate tool parameters - - - Check tool function signatures - -3. **Response Timeout** - - Consider reducing max_tokens - - - Simplify tool complexity - - - -```python -import os -import requests -from dotenv import load_dotenv -import json - -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"} - - -def run_health_check(): - response = requests.get(f"{BASE_URL}/health", headers=headers) - return response.json() - - -def run_single_swarm(): - payload = { - "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": "openai/gpt-4o", - "role": "worker", - "max_loops": 1, - "max_tokens": 8192, - "temperature": 0.5, - "auto_generate_prompt": False, - "tools_dictionary": [ - { - "type": "function", - "function": { - "name": "search_topic", - "description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.", - "parameters": { - "type": "object", - "properties": { - "depth": { - "type": "integer", - "description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.", - }, - "detailed_queries": { - "type": "array", - "description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.", - "items": { - "type": "string", - "description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.", - }, - }, - }, - "required": ["depth", "detailed_queries"], - }, - }, - }, - ], - }, - { - "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, - "tools_dictionary": [ - { - "type": "function", - "function": { - "name": "search_topic", - "description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.", - "parameters": { - "type": "object", - "properties": { - "depth": { - "type": "integer", - "description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.", - }, - "detailed_queries": { - "type": "array", - "description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.", - "items": { - "type": "string", - "description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.", - }, - }, - }, - "required": ["depth", "detailed_queries"], - }, - }, - }, - ], - }, - ], - "max_loops": 1, - "swarm_type": "ConcurrentWorkflow", - "task": "What are the best etfs and index funds for ai and tech?", - "output_type": "dict", - } - - response = requests.post( - f"{BASE_URL}/v1/swarm/completions", - headers=headers, - json=payload, - ) - - print(response) - print(response.status_code) - # return response.json() - output = response.json() - - return json.dumps(output, indent=4) - - -if __name__ == "__main__": - result = run_single_swarm() - print("Swarm Result:") - print(result) - -``` \ No newline at end of file