swarms/docs/swarms_cloud/rust_client.md

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:

cargo install swarms-rs

Quick Start

use swarms_client::SwarmsClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 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<ClientBuilder, SwarmsError>

Example:

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<SwarmsClient, SwarmsError>

Example:

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<ClientBuilder, SwarmsError>	Loads API key from environment
api_key(key)	String	ClientBuilder	Sets the API key
base_url(url)	&str	Result<ClientBuilder, SwarmsError>	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<SwarmsClient, SwarmsError>	Builds the client

Example:

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<SwarmCompletionResponse, SwarmsError>	Creates a swarm completion directly
create_batch(requests)	Vec<SwarmSpec>	Result<Vec<SwarmCompletionResponse>, SwarmsError>	Creates multiple swarm completions
list_types()	None	Result<SwarmTypesResponse, SwarmsError>	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<SwarmCompletionResponse, SwarmsError>	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<AgentCompletionResponse, SwarmsError>	Creates an agent completion directly
create_batch(requests)	Vec<AgentCompletion>	Result<Vec<AgentCompletionResponse>, 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<AgentCompletionResponse, SwarmsError>	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

use swarms_client::{SwarmsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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

use swarms_client::{SwarmsClient, SwarmType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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)

use swarms_client::{SwarmsClient, SwarmType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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

use swarms_client::{SwarmsClient, AgentCompletion, AgentSpec};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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

use swarms_client::{SwarmsClient, SwarmsError, ClientConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 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

use swarms_client::SwarmsClient;
use tracing::{info, warn, error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 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

use swarms_client::{SwarmsClient, SwarmsError};

async fn handle_swarm_request(client: &SwarmsClient, task: &str) -> Result<String, SwarmsError> {
    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:

// 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:

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:

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:

cargo test

Run specific tests:

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.