RunAgent Rust SDK

---

What is RunAgent?

RunAgent is a comprehensive Rust SDK for deploying and managing AI agents with support for multiple frameworks including LangChain, LangGraph, LlamaIndex, and more. Whether you're building chatbots, autonomous agents, or complex AI workflows, RunAgent provides the tools you need to deploy, test, and scale your AI applications.

---

Features

• Multi-Framework Support: LangChain, LangGraph, LlamaIndex, Letta, CrewAI, AutoGen
• Local & Remote Deployment: Deploy agents locally or to remote servers
• Real-time Streaming: WebSocket-based streaming for real-time interactions
• Database Management: SQLite-based agent metadata and history
• Template System: Pre-built templates for rapid setup
• Type Safety: Full Rust type safety with error handling
• Async/Await: Powered by Tokio for async operations

---

Installation

cargo add runagent tokio

Or add manually to Cargo.toml:

[dependencies]
runagent = "0.1.0"
tokio = { version = "1.35", features = ["full"] }
serde_json = "1.0"
futures = "0.3"

---

Quick Start

RunAgent Cloud is the recommended way to get started. Deploy and interact with agents hosted on RunAgent's infrastructure without managing your own servers.

RunAgent Cloud

RunAgent Cloud allows you to deploy and interact with agents hosted on RunAgent's infrastructure. This is the recommended way to get started quickly.

Key Benefits:

• No server setup required
• Automatic scaling
• Managed infrastructure
• Simple authentication via API key

Step 1: Set Up Authentication

Important: You must export your API key before running your application:

export RUNAGENT_API_KEY="your-api-key"

You can get your API key from the RunAgent Dashboard.

Step 2: Connect to Your Agent

When connecting to RunAgent Cloud, set local = false:

use runagent::client::RunAgentClient;

let client = RunAgentClient::new(
    "your-agent-id",      // Your agent ID from RunAgent Cloud
    "agno_print_response", // Entrypoint tag
    false                  // local = false for cloud
).await?;

Step 3: Run Your Agent

Non-Streaming Example:

use runagent::client::RunAgentClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Set RUNAGENT_API_KEY environment variable before running
    let agent_id = "your-agent-id";
    
    // Connect to cloud agent (local = false)
    let client = RunAgentClient::new(agent_id, "agno_print_response", false).await?;
    
    // Run with positional and keyword arguments
    let response = client.run_with_args(
        &[json!("Write small paragraph on how i met your mother tv series")], // positional args
        &[] // no keyword args
    ).await?;
    
    println!("Response: {}", response);
    Ok(())
}

Streaming Example:

use runagent::client::RunAgentClient;
use serde_json::json;
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Set RUNAGENT_API_KEY environment variable before running
    let agent_id = "your-agent-id";
    
    // Connect to cloud agent with streaming entrypoint
    let client = RunAgentClient::new(agent_id, "agno_print_response_stream", false).await?;
    
    // Run with streaming
    let mut stream = client.run_stream(&[
        ("prompt", json!("is investing in AI is good idea?"))
    ]).await?;
    
    while let Some(chunk_result) = stream.next().await {
        match chunk_result {
            Ok(chunk) => println!("{}", chunk),
            Err(e) => {
                println!("Error: {}", e);
                break;
            }
        }
    }
    
    Ok(())
}

Complete Workflow:

# 1. Export your API key
export RUNAGENT_API_KEY="your-api-key"

# 2. Run your application
cargo run

---

Local Development

For local development, you can run agents on your own machine. Set local = true when creating the client.

Basic Agent Interaction (Local)

use runagent::client::RunAgentClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent_id = "your-agent-id";
    
    // Connect to local agent (local = true)
    let client = RunAgentClient::new(agent_id, "lead_score_flow", true).await?;
    
    // Run with keyword arguments only
    let response = client.run_with_args(
        &[], // no positional args
        &[
            ("top_n", json!(1)),
            ("generate_emails", json!(true))
        ]
    ).await?;
    
    println!("Response: {}", serde_json::to_string_pretty(&response)?);
    Ok(())
}

Connecting to Local Agent with Explicit Address

use runagent::client::RunAgentClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent_id = "your-agent-id";
    
    // Connect to local agent with explicit host and port
    let client = RunAgentClient::with_address(
        agent_id,
        "generic",
        true,
        Some("127.0.0.1"),
        Some(8452)
    ).await?;
    
    let response = client.run(&[
        ("message", json!("Hello, world!"))
    ]).await?;
    
    println!("Response: {}", response);
    Ok(())
}

---

Configuration

RunAgent Cloud Setup

Required: Set your API key as an environment variable before running your application:

export RUNAGENT_API_KEY="your-api-key"

Optional: Customize the base URL (defaults to https://api.runagent.ai):

export RUNAGENT_BASE_URL="https://api.runagent.ai"

Local Development Setup

For local development, you can configure cache and logging:

export RUNAGENT_CACHE_DIR="~/.runagent"
export RUNAGENT_LOGGING_LEVEL="info"

Quick Reference

Setting	RunAgent Cloud	Local Development
API Key	Required (RUNAGENT_API_KEY)	Not needed
Base URL	Optional (defaults to https://api.runagent.ai)	Not needed
Client Parameter	local = false	local = true
Agent Location	RunAgent infrastructure	Your local machine

Configuration Builder

You can also configure the SDK programmatically:

use runagent::RunAgentConfig;

let config = RunAgentConfig::new()
    .with_api_key("your-api-key")
    .with_base_url("https://api.runagent.ai")
    .with_logging()
    .build();

---

Architecture

Core Components

• Client: High-level client for agent interaction
• REST Client: HTTP-based client for non-streaming requests
• Socket Client: WebSocket-based client for streaming interactions
• Database: SQLite-based agent history store (optional)
• Serialization: Safe messaging via WebSocket

Optional Features

Enable or disable features in Cargo.toml:

[dependencies]
runagent = { version = "0.1.0", features = ["db"] }

Available features:

• db (default): Enable database support for local agent management

---

API Reference

RunAgentClient

Main client for interacting with RunAgent deployments.

Methods

• new(agent_id, entrypoint_tag, local) - Create a new client

  • agent_id: The agent identifier
  • entrypoint_tag: The entrypoint function tag (e.g., "agno_print_response")
  • local: true for local agents, false for cloud agents

• with_address(agent_id, entrypoint_tag, local, host, port) - Create client with explicit address

• run(input_kwargs) - Run agent with keyword arguments only

  • Returns: RunAgentResult<Value>

• run_with_args(input_args, input_kwargs) - Run agent with both positional and keyword arguments

  • input_args: Slice of positional arguments as Value
  • input_kwargs: Slice of tuples (&str, Value) for keyword arguments

• run_stream(input_kwargs) - Run agent with streaming response

  • Returns: RunAgentResult<Pin<Box<dyn Stream<Item = RunAgentResult<Value>> + Send>>>

• run_stream_with_args(input_args, input_kwargs) - Run agent with streaming and both argument types

• health_check() - Check if the agent is available

• get_agent_architecture() - Get the agent's architecture information

DatabaseService

Database service for managing local agent metadata (requires db feature).

• new(db_path) - Create a new database service
• add_agent(agent) - Add an agent to the database
• list_agents() - List all agents in the database
• get_agent(agent_id) - Get agent information by ID

---

Error Handling

use runagent::{RunAgentError, RunAgentResult};

fn handle_errors() -> RunAgentResult<()> {
    match some_operation() {
        Ok(result) => Ok(result),
        Err(RunAgentError::Authentication { message }) => {
            eprintln!("Auth error: {}", message);
            Err(RunAgentError::authentication("Invalid credentials"))
        }
        Err(RunAgentError::Connection { message }) => {
            eprintln!("Connection error: {}", message);
            Err(RunAgentError::connection("Connection failed"))
        }
        Err(e) => Err(e),
    }
}

---

Testing

cargo test
cargo test --all-features
cargo test --test integration

---

Examples

See the examples/ folder for complete examples:

• Basic usage with cloud agents
• Streaming interactions
• Local agent connections
• Framework integrations

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/runagent-dev/runagent.git
cd runagent/runagent-rust
cargo build
cargo test

---

Roadmap

• Python interop via PyO3
• Additional framework support
• Enhanced streaming capabilities
• Production deployment tools
• Monitoring & observability
• CLI tool integration

---

Links

• Website
• Documentation
• Repository
• Issues
• Python SDK

---

License

This project is licensed under the MIT License - see the LICENSE file.

---

Acknowledgments

• Built with Tokio
• Uses Axum
• SQL powered by SQLx
• WebSocket support via tokio-tungstenite

---

Need help? Join our Discord or check the documentation!