# rswarm: A Comprehensive Guide to AI Agent Interactions in Rust Welcome, fellow Rustacean! If you’re aiming to integrate advanced AI agent interactions into your Rust applications, you’ve come to the right place. rswarm is a powerful and user-friendly library designed to simplify and enhance your AI development experience in Rust. Embark on this journey with us as we explore how rswarm can empower your projects with intelligent agent capabilities. ## Introduction rswarm is a Rust library crafted to streamline AI agent interactions, particularly when working with OpenAI’s API. It provides a robust framework for: - **Managing AI agents with customizable behaviors**: Define agents with specific instructions and functions tailored to your application’s needs. - **Executing conversations with advanced control**: Run complex dialogues with agents, controlling parameters like context, functions, and looping behaviors. - **Integrating custom functions for extended capabilities**: Enhance agents with custom functions that can be called during conversations. - **Handling streaming responses and error scenarios gracefully**: Receive real-time responses and implement robust error handling mechanisms. - **Defining prompts and execution steps using XML**: Utilize XML to structure prompts, handoffs, function calls, and execution steps for more complex interactions. Whether you’re building a chatbot, an AI assistant, or any application requiring intelligent dialogue, rswarm equips you with the tools to make it happen efficiently. ## Acknowledgments This project, rswarm, is inspired by and extends the concepts introduced in the [Swarm](https://github.com/openai/swarm) framework developed by OpenAI. Swarm is an educational framework that explores ergonomic, lightweight multi-agent orchestration. It provides a foundation for agent coordination and execution through abstractions like Agents and handoffs, allowing for scalable and customizable solutions. We would like to express our gratitude to the OpenAI team for their innovative work on Swarm, which has significantly influenced the development of rswarm. Special thanks to the core contributors of Swarm, including Ilan Bigio, James Hills, Shyamal Anadkat, Charu Jaiswal, Colin Jarvis, and Katia Gil Guzman, among others. By building upon Swarm, rswarm aims to bring these powerful concepts into the Rust ecosystem, enhancing them to suit our specific needs and preferences. We hope to continue pushing the boundaries of what's possible with Rust and AI, inspired by the groundwork laid by OpenAI. Feel free to explore the rswarm framework further, contribute to its development, or reach out with questions. Together, we can continue to innovate and expand the capabilities of AI agent interactions. Happy coding! ## Installation To get started with rswarm, you need to add it to your project’s dependencies. Ensure you have Rust and Cargo installed on your system. ### Adding rswarm to Your Project In your `Cargo.toml` file, add: ```bash cargo add rswarm ``` After updating `Cargo.toml`, fetch the dependencies by running: ```bash cargo build ``` ### Setting Up Environment Variables rswarm relies on environment variables for configuration: - **OPENAI_API_KEY (required)**: Your OpenAI API key. - **OPENAI_API_URL (optional)**: Custom API URL if not using the default. Set them in your shell or a `.env` file: ```bash export OPENAI_API_KEY="your-api-key" export OPENAI_API_URL="https://api.openai.com/v1/chat/completions" # Optional ``` In your Rust application, load the `.env` file: ```rust dotenv::dotenv().ok(); ``` > **Note**: Keep your API key secure and avoid committing it to version control. ## Quick Start Let’s dive into a basic example to see rswarm in action. ### Creating a Swarm Instance The `Swarm` struct is the heart of the library, managing API communication and agent interactions. You can create a Swarm instance using the builder pattern. #### Using the Builder Pattern ```rust use rswarm::Swarm; let swarm = Swarm::builder() .build() .expect("Failed to create Swarm"); ``` If you’ve set the `OPENAI_API_KEY` environment variable, you can omit the `.with_api_key()` method. If you prefer to pass the API key directly: ```rust let swarm = Swarm::builder() .with_api_key("your-api-key".to_string()) .build() .expect("Failed to create Swarm"); ``` ### Defining Agents An `Agent` encapsulates the behavior and capabilities of an AI assistant. #### Creating an Agent ```rust use rswarm::{Agent, Instructions}; let agent = Agent { name: "assistant".to_string(), model: "gpt-3.5-turbo".to_string(), instructions: Instructions::Text("You are a helpful assistant.".to_string()), functions: vec![], function_call: None, parallel_tool_calls: false, }; ``` #### Understanding Instructions Instructions guide the agent’s behavior. They can be: - **Static Text**: Fixed instructions provided as a `String`. - **Dynamic Functions**: Generate instructions based on context using a closure. Example of dynamic instructions: ```rust use rswarm::{Instructions, ContextVariables}; use std::sync::Arc; let dynamic_instructions = Instructions::Function(Arc::new(|context: ContextVariables| { format!( "You are a helpful assistant aware of the user's location: {}.", context.get("location").unwrap_or(&"unknown".to_string()) ) })); ``` ### Running Conversations Let’s initiate a conversation with our agent. #### Initiating a Chat ```rust use rswarm::{Message, ContextVariables}; use std::collections::HashMap; let messages = vec![Message { role: "user".to_string(), content: Some("Hello, assistant!".to_string()), name: None, function_call: None, }]; let context_variables = ContextVariables::new(); // An empty context let response = swarm .run( agent.clone(), messages, context_variables, None, // No model override false, // Streaming disabled false, // Debug mode off 5 // Max turns ) .await .expect("Failed to run the conversation"); for msg in response.messages { println!("{}: {}", msg.role, msg.content.unwrap_or_default()); } ``` The agent responds according to the instructions provided. ## Deep Dive Let’s explore rswarm in greater detail, uncovering its full potential. ### Swarm Configuration Customize Swarm behavior using `SwarmConfig`. #### Custom Configuration ```rust use rswarm::{Swarm, SwarmConfig}; let custom_config = SwarmConfig { request_timeout: 60, max_retries: 5, ..Default::default() }; let swarm = Swarm::builder() .with_config(custom_config) .build() .expect("Failed to create Swarm with custom configuration"); ``` Adjust parameters like timeouts and retries based on application needs. ### Agent Functions Agents can execute custom functions, extending their capabilities. #### Defining Agent Functions ```rust use rswarm::{AgentFunction, ContextVariables, ResultType}; use std::sync::Arc; let echo_function = AgentFunction { name: "echo".to_string(), function: Arc::new(|args: ContextVariables| { let message = args.get("message").cloned().unwrap_or_default(); Ok(ResultType::Value(message)) }), accepts_context_variables: true, }; ``` #### Adding Functions to an Agent ```rust agent.functions.push(echo_function); agent.function_call = Some("auto".to_string()); ``` With `function_call` set to `"auto"`, the agent decides when to use the functions. ### Context Variables Context variables provide dynamic data to agents. #### Using Context Variables ```rust let mut context_variables = ContextVariables::new(); context_variables.insert("location".to_string(), "Berlin".to_string()); let dynamic_instructions = Instructions::Function(Arc::new(|context: ContextVariables| { format!( "You are a helpful assistant. The user's location is {}.", context.get("location").unwrap() ) })); agent.instructions = dynamic_instructions; ``` The agent tailors responses based on the context provided. ### Handling Function Calls Agents can call functions during conversations to perform specific tasks. #### Implementing Function Handling First, define a function: ```rust use rswarm::{AgentFunction, ContextVariables, ResultType}; use std::sync::Arc; // Define the echo function let echo_function = AgentFunction { name: "echo".to_string(), function: Arc::new(|args: ContextVariables| { let message = args.get("message").cloned().unwrap_or_default(); Ok(ResultType::Value(message)) }), accepts_context_variables: true, }; // Add the function to the agent let mut agent = Agent { name: "assistant".to_string(), model: "gpt-3.5-turbo".to_string(), instructions: Instructions::Text("You are a helpful assistant.".to_string()), functions: vec![echo_function], // Add the function here function_call: Some("auto".to_string()), // Allow the agent to call functions parallel_tool_calls: false, }; // Now use the agent in conversation let messages = vec![Message { role: "user".to_string(), content: Some("Repeat after me: Hello World!".to_string()), name: None, function_call: None, }]; let response = swarm .run( agent.clone(), messages, ContextVariables::new(), None, false, false, 5 ) .await .expect("Failed to run the conversation"); for msg in response.messages { println!("{}: {}", msg.role, msg.content.unwrap_or_default()); } ``` In this example, we define an echo function that the agent can use to repeat messages. The agent will automatically decide when to use this function based on the conversation context. ### Streaming Responses For real-time applications, enable streaming to receive incremental responses. #### Enabling Streaming ```rust let response = swarm .run( agent.clone(), messages.clone(), context_variables.clone(), None, true, // Enable streaming false, // Debug mode off 5 ) .await .expect("Failed to run the conversation"); ``` ### Error Handling and Retries Robust error handling ensures a smooth user experience. #### Configuring Retries ```rust let custom_config = SwarmConfig { max_retries: 5, ..Default::default() }; let swarm = Swarm::builder() .with_config(custom_config) .build() .expect("Failed to create Swarm with custom configuration"); ``` #### Implementing Retry Logic ```rust use rswarm::SwarmError; match swarm.run(/* parameters */).await { Ok(response) => { // Process the response } Err(e) => { if e.is_retriable() { // Implement retry logic } else { eprintln!("An error occurred: {}", e); } } } ``` ### Defining Prompts and Execution Steps with XML rswarm allows you to define complex interactions using XML, including prompts, handoffs, function calls, and execution steps. This feature enables you to structure conversations and control agent behavior in a more organized manner. #### Using XML to Define Steps You can embed XML within the agent’s instructions to define a sequence of steps for the agent to execute. ##### Example of XML Steps ```xml Introduce yourself. Answer the user's questions until they say 'goodbye'. ``` #### How It Works - **Step Number**: Indicates the order of execution. - **Action**: Defines what the agent should do (run_once, loop). - **Agent (Optional)**: Specifies which agent to use for the step. - **Prompt**: The instruction or message for the agent. #### Parsing XML Steps The library provides functions to extract and parse these steps from the instructions. ```rust use rswarm::{extract_xml_steps, parse_steps_from_xml, Steps}; let instructions = r#" You are about to engage in a conversation. Introduce yourself. Answer the user's questions until they say 'goodbye'. Proceed with the conversation. "#; // Extract XML steps let (instructions_without_xml, xml_steps) = extract_xml_steps(instructions).unwrap(); // Parse the steps let steps = if let Some(xml_content) = xml_steps { parse_steps_from_xml(&xml_content).unwrap() } else { Steps { steps: Vec::new() } }; // Now you can use `steps` in your conversation logic ``` #### Executing Steps The Swarm’s `run()` method automatically handles the execution of steps defined in XML. ```rust let response = swarm .run( agent.clone(), messages, context_variables, None, false, false, 10 ) .await .expect("Failed to run the conversation with steps"); ``` #### Step Actions - **run_once**: Executes the step’s prompt once. - **loop**: Repeats the step’s prompt until a termination condition is met. #### Agent Handoffs By specifying an agent in a step, you can switch agents during the conversation. ```xml Provide detailed answers to the user's technical questions. ``` In the above example, the conversation hands off to `specialist_agent` for step 2. ## Advanced Topics Delve deeper into rswarm’s capabilities. ### Managing Multiple Agents Handle complex applications with multiple agents. #### Registering Agents ```rust // Register the initial agent swarm.agent_registry.insert(agent.name.clone(), agent.clone()); // Define another agent let assistant_agent = Agent { name: "general_assistant".to_string(), model: "gpt-4".to_string(), instructions: Instructions::Text("You are a general-purpose assistant.".to_string()), functions: vec![], function_call: None, parallel_tool_calls: false, }; // Register the new agent swarm.agent_registry.insert(assistant_agent.name.clone(), assistant_agent.clone()); ``` #### Switching Agents ```rust let mut current_agent = swarm.get_agent_by_name("general_assistant") .expect("Agent not found"); if user_requests_specialized_info { current_agent = swarm.get_agent_by_name("specialist_agent") .expect("Agent not found"); } ``` ### Custom Instruction Functions Dynamic instructions adapt agent behavior in real-time. #### Example ```rust let custom_instructions = Instructions::Function(Arc::new(|context: ContextVariables| { let user_role = context.get("role").unwrap_or(&"user".to_string()); format!("You are assisting a {}.", user_role) })); agent.instructions = custom_instructions; ``` ### Loop Control and Execution Steps Control complex conversation flows with loop control and execution steps. #### Implementing Loop Control When using the `loop` action in XML steps, rswarm handles loop execution and termination conditions. - **Termination Condition**: The loop ends when the `context_variables` contain a key that matches a break condition (e.g., `"end_loop": "true"`). - **Max Iterations**: Prevent infinite loops by setting `max_loop_iterations` in `SwarmConfig`. ```rust let custom_config = SwarmConfig { max_loop_iterations: 5, ..Default::default() }; let swarm = Swarm::builder() .with_config(custom_config) .build() .expect("Failed to create Swarm with custom configuration"); ``` Within your function, you can set `context_variables` to signal loop termination. ```rust let end_loop_function = AgentFunction { name: "end_loop".to_string(), function: Arc::new(|mut args: ContextVariables| { args.insert("end_loop".to_string(), "true".to_string()); Ok(ResultType::ContextVariables(args)) }), accepts_context_variables: true, }; // Add the function to the agent agent.functions.push(end_loop_function); ``` ### Utilizing the Utility Functions rswarm provides utility functions to assist with debugging and processing. #### Debug Printing ```rust use rswarm::debug_print; debug_print(true, "This is a debug message."); ``` #### Merging Chunked Messages When handling streaming responses, use `merge_chunk_message` to assemble messages. ```rust use rswarm::{Message, merge_chunk_message}; use serde_json::json; let mut message = Message { role: "assistant".to_string(), content: Some("Hello".to_string()), name: None, function_call: None, }; let delta = json!({ "content": " world!" }).as_object().unwrap().clone(); merge_chunk_message(&mut message, &delta); assert_eq!(message.content, Some("Hello world!".to_string())); ``` ### Validation and Error Handling Ensure your application handles errors gracefully by utilizing the validation functions provided by rswarm. #### Validating API Requests ```rust use rswarm::validation::validate_api_request; validate_api_request(&agent, &messages, &None, 5) .expect("Validation failed"); ``` #### Validating API URLs ```rust use rswarm::validation::validate_api_url; let api_url = "https://api.openai.com/v1/chat/completions"; validate_api_url(api_url, &swarm.config) .expect("Invalid API URL"); ``` ## Best Practices - **Secure API Keys**: Use environment variables and avoid hardcoding sensitive information. - **Handle Errors Gracefully**: Implement retry logic and provide user-friendly error messages. - **Optimize Performance**: Adjust timeouts and retries based on application needs. - **Keep Agents Modular**: Design agents with single responsibilities for easier maintenance. - **Leverage Context**: Use context variables to enhance agent responses dynamically. - **Use XML for Complex Flows**: Utilize XML definitions for structured and maintainable conversation flows. - **Test Thoroughly**: Write tests to ensure your agents and functions work as expected. ## Conclusion We’ve explored the landscape of rswarm, uncovering how it can elevate your Rust applications with intelligent AI interactions. From setting up a basic conversation to mastering advanced features like XML-defined execution steps, you’re now equipped to harness the full power of this library. As you continue your development journey, remember that innovation thrives on experimentation. Don’t hesitate to explore new ideas, contribute to the rswarm community, and push the boundaries of what’s possible with Rust and AI. Happy coding! ## Appendix: API Reference ### Swarm Struct ```rust pub struct Swarm { pub client: Client, pub api_key: String, pub agent_registry: HashMap, pub config: SwarmConfig, } ``` - **Purpose**: Manages API communication and agent interactions. - **Key Methods**: - `run()`: Executes a conversation. - `builder()`: Initializes a `SwarmBuilder`. - `get_agent_by_name()`: Retrieves an agent from the registry. ### Agent Struct ```rust pub struct Agent { pub name: String, pub model: String, pub instructions: Instructions, pub functions: Vec, pub function_call: Option, pub parallel_tool_calls: bool, } ``` - **Purpose**: Defines an AI assistant’s behavior. - **Fields**: - `name`: Unique identifier. - `model`: AI model to use (e.g., "gpt-3.5-turbo"). - `instructions`: Guides the agent’s responses. - `functions`: Custom functions the agent can call. - `function_call`: Determines when functions are called. - `parallel_tool_calls`: Enables parallel execution of functions. ### AgentFunction Struct ```rust pub struct AgentFunction { pub name: String, pub function: Arc Result + Send + Sync>, pub accepts_context_variables: bool, } ``` - **Purpose**: Enables agents to execute custom logic. - **Fields**: - `name`: Function identifier. - `function`: The executable function. - `accepts_context_variables`: Indicates if it uses context variables. ### SwarmConfig Struct ```rust pub struct SwarmConfig { pub api_url: String, pub api_version: String, pub request_timeout: u64, pub connect_timeout: u64, pub max_retries: u32, pub max_loop_iterations: u32, pub valid_model_prefixes: Vec, pub valid_api_url_prefixes: Vec, pub loop_control: LoopControl, pub api_settings: ApiSettings, } ``` - **Purpose**: Configures Swarm behavior. - **Fields**: - `api_url`: The OpenAI API URL. - `request_timeout`: Max time for each API request. - `connect_timeout`: Max time to establish a connection. - `max_retries`: Max retry attempts for failed requests. - `max_loop_iterations`: Limits to prevent infinite loops. - `loop_control`: Settings for loop execution. - `api_settings`: Advanced API configurations. ### Instructions Enum ```rust pub enum Instructions { Text(String), Function(Arc String + Send + Sync>), } ``` - **Purpose**: Defines agent instructions. - **Variants**: - `Text`: Static instructions. - `Function`: Dynamic instructions based on context. ### ContextVariables Type ```rust pub type ContextVariables = HashMap; ``` - **Purpose**: Stores key-value pairs for context within conversations. ### ResultType Enum ```rust pub enum ResultType { Value(String), Agent(Agent), ContextVariables(ContextVariables), } ``` - **Purpose**: Represents the result of an agent function execution. ### Steps Struct ```rust pub struct Steps { pub steps: Vec, } ``` - **Purpose**: Represents a sequence of execution steps defined in XML. ### Step Struct ```rust pub struct Step { pub number: usize, pub action: String, pub agent: Option, pub prompt: String, } ``` - **Purpose**: Defines a single execution step. - **Fields**: - `number`: The sequence number of the step. - `action`: The action to perform (run_once, loop). - `agent`: Optional agent name for handoff. - `prompt`: The prompt to execute. ## License This project is licensed under the MIT License. ## Acknowledgments A heartfelt thank you to all contributors and the Rust community. Your support and collaboration make projects like rswarm possible. Feel free to explore the library further, contribute to its development, or reach out with questions. Together, we can continue to push the boundaries of what’s possible with Rust and AI. Happy coding!