# 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 | | `DeepResearchSwarm` | Specialized for deep research 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.