Crates.io | rswarm |
lib.rs | rswarm |
version | 0.1.2 |
source | src |
created_at | 2024-11-21 18:02:16.231456 |
updated_at | 2024-11-21 18:08:25.323766 |
description | A Rust implementation of the Swarm framework |
homepage | |
repository | |
max_upload_size | |
id | 1456512 |
size | 104,190 |
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.
rswarm is a Rust library crafted to streamline AI agent interactions, particularly when working with OpenAI’s API. It provides a robust framework for:
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.
This project, rswarm, is inspired by and extends the concepts introduced in the 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 Swarm 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!
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.
In your Cargo.toml
file, add:
cargo add rswarm
or
[dependencies]
rswarm = { git = "https://github.com/socrates8300/rswarm.git" }
After updating Cargo.toml
, fetch the dependencies by running:
cargo build
rswarm relies on environment variables for configuration:
Set them in your shell or a .env
file:
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:
dotenv::dotenv().ok();
Note: Keep your API key secure and avoid committing it to version control.
Let’s dive into a basic example to see rswarm in action.
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.
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:
let swarm = Swarm::builder()
.with_api_key("your-api-key".to_string())
.build()
.expect("Failed to create Swarm");
An Agent
encapsulates the behavior and capabilities of an AI assistant.
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,
};
Instructions guide the agent’s behavior. They can be:
String
.Example of dynamic instructions:
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())
)
}));
Let’s initiate a conversation with our agent.
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.
Let’s explore rswarm in greater detail, uncovering its full potential.
Customize Swarm behavior using SwarmConfig
.
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.
Agents can execute custom functions, extending their capabilities.
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,
};
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 provide dynamic data to agents.
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.
Agents can call functions during conversations to perform specific tasks.
First, define a function:
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.
For real-time applications, enable streaming to receive incremental responses.
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");
Robust error handling ensures a smooth user experience.
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");
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);
}
}
}
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.
You can embed XML within the agent’s instructions to define a sequence of steps for the agent to execute.
<steps>
<step number="1" action="run_once">
<prompt>Introduce yourself.</prompt>
</step>
<step number="2" action="loop" agent="assistant">
<prompt>Answer the user's questions until they say 'goodbye'.</prompt>
</step>
</steps>
The library provides functions to extract and parse these steps from the instructions.
use rswarm::{extract_xml_steps, parse_steps_from_xml, Steps};
let instructions = r#"
You are about to engage in a conversation.
<steps>
<step number="1" action="run_once">
<prompt>Introduce yourself.</prompt>
</step>
<step number="2" action="loop" agent="assistant">
<prompt>Answer the user's questions until they say 'goodbye'.</prompt>
</step>
</steps>
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
The Swarm’s run()
method automatically handles the execution of steps defined in XML.
let response = swarm
.run(
agent.clone(),
messages,
context_variables,
None,
false,
false,
10
)
.await
.expect("Failed to run the conversation with steps");
By specifying an agent in a step, you can switch agents during the conversation.
<step number="2" action="loop" agent="specialist_agent">
<prompt>Provide detailed answers to the user's technical questions.</prompt>
</step>
In the above example, the conversation hands off to specialist_agent
for step 2.
Delve deeper into rswarm’s capabilities.
Handle complex applications with multiple agents.
// 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());
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");
}
Dynamic instructions adapt agent behavior in real-time.
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;
Control complex conversation flows with loop control and execution steps.
When using the loop
action in XML steps, rswarm handles loop execution and termination conditions.
context_variables
contain a key that matches a break condition (e.g., "end_loop": "true"
).max_loop_iterations
in SwarmConfig
.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.
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);
rswarm provides utility functions to assist with debugging and processing.
use rswarm::debug_print;
debug_print(true, "This is a debug message.");
When handling streaming responses, use merge_chunk_message
to assemble messages.
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()));
Ensure your application handles errors gracefully by utilizing the validation functions provided by rswarm.
use rswarm::validation::validate_api_request;
validate_api_request(&agent, &messages, &None, 5)
.expect("Validation failed");
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");
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!
pub struct Swarm {
pub client: Client,
pub api_key: String,
pub agent_registry: HashMap<String, Agent>,
pub config: SwarmConfig,
}
run()
: Executes a conversation.builder()
: Initializes a SwarmBuilder
.get_agent_by_name()
: Retrieves an agent from the registry.pub struct Agent {
pub name: String,
pub model: String,
pub instructions: Instructions,
pub functions: Vec<AgentFunction>,
pub function_call: Option<String>,
pub parallel_tool_calls: bool,
}
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.pub struct AgentFunction {
pub name: String,
pub function: Arc<dyn Fn(ContextVariables) -> Result<ResultType> + Send + Sync>,
pub accepts_context_variables: bool,
}
name
: Function identifier.function
: The executable function.accepts_context_variables
: Indicates if it uses context variables.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<String>,
pub valid_api_url_prefixes: Vec<String>,
pub loop_control: LoopControl,
pub api_settings: ApiSettings,
}
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.pub enum Instructions {
Text(String),
Function(Arc<dyn Fn(ContextVariables) -> String + Send + Sync>),
}
Text
: Static instructions.Function
: Dynamic instructions based on context.pub type ContextVariables = HashMap<String, String>;
pub enum ResultType {
Value(String),
Agent(Agent),
ContextVariables(ContextVariables),
}
pub struct Steps {
pub steps: Vec<Step>,
}
pub struct Step {
pub number: usize,
pub action: String,
pub agent: Option<String>,
pub prompt: String,
}
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.This project is licensed under the MIT License.
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!