Composio Rust SDK

A minimal, type-safe Rust SDK for the Composio Tool Router REST API.

Features

• 🦀 Type-Safe: Compile-time validation with Rust's type system
• ⚡ Async/Await: Built on tokio for high-performance async operations
• 🔄 Automatic Retries: Exponential backoff for transient failures
• 📦 Minimal Footprint: ~2 MB memory overhead
• 🛡️ Error Handling: Comprehensive error types with actionable messages
• 🔧 Session Management: User-scoped sessions for data isolation

Installation

Add this to your Cargo.toml:

[dependencies]

composio-sdk = "0.1.0"

tokio = { version = "1.0", features = ["full"] }

Quick Start

use composio_sdk::{ComposioClient, ComposioError};

#[tokio::main]
async fn main() -> Result<(), ComposioError> {
    // Initialize the client
    let client = ComposioClient::builder()
        .api_key(std::env::var("COMPOSIO_API_KEY")?)
        .build()?;

    // Create a session for a user
    let session = client
        .create_session("user_123")
        .toolkits(vec!["github", "gmail"])
        .manage_connections(true)
        .send()
        .await?;

    println!("Session ID: {}", session.session_id());
    println!("MCP URL: {}", session.mcp_url());

    // Execute a tool
    let result = session
        .execute_tool(
            "GITHUB_CREATE_ISSUE",
            serde_json::json!({
                "owner": "composio",
                "repo": "composio",
                "title": "Test issue",
                "body": "Created via Rust SDK"
            })
        )
        .await?;

    println!("Result: {:?}", result.data);

    Ok(())
}

Core Concepts

Sessions

Sessions provide user-scoped access to tools and manage authentication:

// Create a session with specific toolkits
let session = client
    .create_session("user_123")
    .toolkits(vec!["github", "gmail", "slack"])
    .send()
    .await?;

// Disable specific toolkits
let session = client
    .create_session("user_456")
    .disable_toolkits(vec!["exa", "firecrawl"])
    .send()
    .await?;

Tool Execution

Execute tools within a session:

// Execute a regular tool
let result = session
    .execute_tool("GMAIL_SEND_EMAIL", serde_json::json!({
        "to": "user@example.com",
        "subject": "Hello from Rust",
        "body": "This email was sent using Composio Rust SDK"
    }))
    .await?;

// Execute a meta tool
let search_result = session
    .execute_meta_tool(
        MetaToolSlug::ComposioSearchTools,
        serde_json::json!({
            "query": "create a GitHub issue"
        })
    )
    .await?;

Error Handling

The SDK provides comprehensive error handling:

use composio_sdk::ComposioError;

match session.execute_tool("INVALID_TOOL", serde_json::json!({})).await {
    Ok(result) => println!("Success: {:?}", result),
    Err(ComposioError::ApiError { status, message, suggested_fix, .. }) => {
        eprintln!("API error ({}): {}", status, message);
        if let Some(fix) = suggested_fix {
            eprintln!("Suggested fix: {}", fix);
        }
    }
    Err(ComposioError::NetworkError(e)) => {
        eprintln!("Network error: {}", e);
    }
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}

Configuration

Customize client behavior:

use std::time::Duration;

let client = ComposioClient::builder()
    .api_key("your-api-key")
    .base_url("https://backend.composio.dev/api/v3")
    .timeout(Duration::from_secs(30))
    .max_retries(3)
    .initial_retry_delay(Duration::from_secs(1))
    .max_retry_delay(Duration::from_secs(10))
    .build()?;

Authentication

In-Chat Authentication (Default)

The agent automatically prompts users with Connect Links during conversation:

let session = client
    .create_session("user_123")
    .toolkits(vec!["github"])
    .manage_connections(true)  // Default: true
    .send()
    .await?;

// Agent will automatically handle authentication when needed

Manual Authentication

Pre-authenticate users before they start chatting:

// Create auth link
let link = session
    .create_auth_link("github", Some("https://yourapp.com/callback"))
    .await?;

println!("Redirect user to: {}", link.redirect_url);

// Check connection status
let toolkits = session.list_toolkits().send().await?;
for toolkit in toolkits.items {
    if toolkit.slug == "github" {
        if let Some(account) = toolkit.connected_account {
            println!("GitHub connected: {}", account.status);
        }
    }
}

Toolkit Management

List and filter available toolkits:

// List all toolkits
let toolkits = session.list_toolkits().send().await?;

// Filter by connection status
let connected = session
    .list_toolkits()
    .is_connected(true)
    .send()
    .await?;

// Search toolkits
let results = session
    .list_toolkits()
    .search("email")
    .send()
    .await?;

Meta Tools

The SDK supports all 5 meta tools:

use composio_sdk::MetaToolSlug;

// Search for tools
let search = session.execute_meta_tool(
    MetaToolSlug::ComposioSearchTools,
    serde_json::json!({ "query": "send email" })
).await?;

// Execute multiple tools in parallel
let multi = session.execute_meta_tool(
    MetaToolSlug::ComposioMultiExecuteTool,
    serde_json::json!({
        "tools": [
            { "tool_slug": "GITHUB_GET_REPOS", "arguments": { "owner": "composio" } },
            { "tool_slug": "GITHUB_GET_ISSUES", "arguments": { "owner": "composio", "repo": "composio" } }
        ]
    })
).await?;

// Manage connections
let manage = session.execute_meta_tool(
    MetaToolSlug::ComposioManageConnections,
    serde_json::json!({ "action": "list" })
).await?;

// Remote workbench (Python sandbox)
let workbench = session.execute_meta_tool(
    MetaToolSlug::ComposioRemoteWorkbench,
    serde_json::json!({ "code": "import pandas as pd\ndf = pd.DataFrame({'a': [1, 2, 3]})\nprint(df)" })
).await?;

// Remote bash
let bash = session.execute_meta_tool(
    MetaToolSlug::ComposioRemoteBashTool,
    serde_json::json!({ "command": "ls -la" })
).await?;

Examples

See the examples/ directory for complete working examples:

• basic_usage.rs - Session creation and tool execution
• meta_tools.rs - Using meta tools
• error_handling.rs - Error handling patterns
• authentication.rs - Authentication flows
• toolkit_listing.rs - Listing and filtering toolkits

Run an example:

cargo run --example basic_usage

Requirements

• Rust 1.70 or later
• Tokio runtime
• Composio API key (get one here)

Memory Footprint

The SDK is designed for minimal memory usage:

• Library size: 2.45 MB (release build)
• Runtime overhead: 112 bytes (client) + 296 bytes (session builder)
• Initialization time: ~200 µs (client creation)
• Text section: 28 KiB (SDK code only, excluding dependencies)

Performance Characteristics

• Zero-copy deserialization where possible
• Efficient Arc-based sharing for client references
• Minimal stack allocation
• Suitable for resource-constrained environments

Optimization Options

For production builds, add to your Cargo.toml:

[profile.release]

lto = true             # Link-time optimization (15-20% size reduction)

codegen-units = 1      # Better optimization

strip = true           # Strip debug symbols

See MEMORY_FOOTPRINT_REPORT.md for detailed analysis.

API Coverage

This SDK focuses on the Tool Router API:

• ✅ Session creation and retrieval
• ✅ Tool execution (regular and meta tools)
• ✅ Toolkit listing and filtering
• ✅ Authentication link creation
• ✅ Meta tools schema retrieval
• ✅ Automatic retry with exponential backoff
• ✅ Comprehensive error handling

Roadmap

Future enhancements:

• Direct tool execution (non-session)
• Triggers support
• Connected accounts management
• Auth configs management
• File upload/download
• Workbench mount operations

Note: Wizard instruction generation requires the Composio Skills repository for development. This feature is not available in the published crate but can be enabled by cloning the Skills repository to vendor/skills during development.

Documentation

• API Documentation
• Composio Platform Docs
• Examples

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Support

• Discord Community
• GitHub Issues
• Documentation

Acknowledgments

This SDK is built for ZeroClaw, a lightweight Rust AI assistant, and follows the design patterns from the official Composio Python SDK.