Getting Started

Learn how to build your first multi-agent system with Agentropic in just a few minutes.

Installation

Add Agentropic to your Rust project by including the necessary crates in your Cargo.toml:

Cargo.tomltoml

# Add to your Cargo.toml
[dependencies]
agentropic-core = "0.1"
agentropic-messaging = "0.1"
tokio = { version = "1", features = ["full"] }

Your First Agent

Define an agent using the #[derive(Agent)] macro and implement the AgentBehavior trait:

src/greeter.rsrust

1use agentropic_core::prelude::*;
2
3// Define your agent with a derive macro
4#[derive(Agent)]
5pub struct GreeterAgent {
6    name: String,
7    greeting_count: u32,
8}
9
10// Implement the agent behavior
11impl AgentBehavior for GreeterAgent {
12    type Message = GreetingMessage;
13
14    async fn on_start(&mut self) -> Result<()> {
15        println!("{} is ready to greet!", self.name);
16        Ok(())
17    }
18
19    async fn on_message(&mut self, msg: Self::Message) -> Result<()> {
20        self.greeting_count += 1;
21        println!("{}: Hello, {}! (Greeting #{})", 
22            self.name, msg.recipient, self.greeting_count);
23        Ok(())
24    }
25
26    async fn on_stop(&mut self) -> Result<()> {
27        println!("{} said {} greetings total", 
28            self.name, self.greeting_count);
29        Ok(())
30    }
31}
32
33#[derive(Debug, Clone)]
34pub struct GreetingMessage {
35    pub recipient: String,
36}

Key concepts: Agents have a lifecycle with on_start, on_message, and on_stop hooks. The derive macro generates boilerplate for state management and spawning.

Message Passing

Agents communicate through typed channels. Create a channel, spawn the agent with the receiver, and use the sender to dispatch messages:

src/main.rsrust

1use agentropic_messaging::{Channel, Address};
2
3#[tokio::main]
4async fn main() -> Result<()> {
5    // Create a channel for the agent
6    let (tx, rx) = Channel::<GreetingMessage>::bounded(100);
7    
8    // Spawn the agent
9    let agent = GreeterAgent {
10        name: "Alice".into(),
11        greeting_count: 0,
12    };
13    let handle = agent.spawn(rx).await?;
14    
15    // Send messages to the agent
16    tx.send(GreetingMessage { 
17        recipient: "Bob".into() 
18    }).await?;
19    
20    tx.send(GreetingMessage { 
21        recipient: "Charlie".into() 
22    }).await?;
23    
24    // Gracefully stop the agent
25    handle.stop().await?;
26    
27    Ok(())
28}