Skip to main content

mojentic/agents/
async_llm_agent.rs

1//! Async LLM-powered agent implementation.
2//!
3//! This module provides an agent that uses an LLM to generate responses to events.
4//! It supports system prompts (behaviour), structured output via response models,
5//! and tool calling.
6
7use crate::agents::BaseAsyncAgent;
8use crate::event::Event;
9use crate::llm::{LlmBroker, LlmMessage, LlmTool};
10use crate::Result;
11use async_trait::async_trait;
12use serde::{Deserialize, Serialize};
13use std::sync::Arc;
14
15/// An async agent powered by an LLM.
16///
17/// This agent uses an LLM broker to generate responses. It can be configured
18/// with a system prompt (behaviour), optional tools, and a response model for
19/// structured output.
20///
21/// # Examples
22///
23/// ```ignore
24/// use mojentic::agents::AsyncLlmAgent;
25/// use mojentic::llm::LlmBroker;
26///
27/// let broker = Arc::new(LlmBroker::new("model-name", gateway, None));
28/// let agent = AsyncLlmAgent::new(
29///     broker,
30///     "You are a helpful assistant.",
31///     None, // tools
32/// );
33/// ```
34pub struct AsyncLlmAgent {
35    broker: Arc<LlmBroker>,
36    behaviour: String,
37    tools: Vec<Box<dyn LlmTool>>,
38}
39
40impl AsyncLlmAgent {
41    /// Create a new AsyncLlmAgent.
42    ///
43    /// # Arguments
44    ///
45    /// * `broker` - The LLM broker to use for generating responses
46    /// * `behaviour` - System prompt defining the agent's personality and behavior
47    /// * `tools` - Optional tools available to the LLM
48    pub fn new(
49        broker: Arc<LlmBroker>,
50        behaviour: impl Into<String>,
51        tools: Option<Vec<Box<dyn LlmTool>>>,
52    ) -> Self {
53        Self {
54            broker,
55            behaviour: behaviour.into(),
56            tools: tools.unwrap_or_default(),
57        }
58    }
59
60    /// Add a tool to the agent.
61    ///
62    /// # Arguments
63    ///
64    /// * `tool` - The tool to add
65    pub fn add_tool(&mut self, tool: Box<dyn LlmTool>) {
66        self.tools.push(tool);
67    }
68
69    /// Generate a text response using the LLM.
70    ///
71    /// # Arguments
72    ///
73    /// * `content` - The user message content
74    /// * `correlation_id` - Optional correlation ID for tracing
75    ///
76    /// # Returns
77    ///
78    /// The generated text response
79    pub async fn generate_response(
80        &self,
81        content: &str,
82        correlation_id: Option<String>,
83    ) -> Result<String> {
84        let messages = vec![
85            LlmMessage::system(&self.behaviour),
86            LlmMessage::user(content),
87        ];
88
89        let tools = if self.tools.is_empty() {
90            None
91        } else {
92            Some(self.tools.as_slice())
93        };
94
95        self.broker.generate(&messages, tools, None, correlation_id).await
96    }
97
98    /// Generate a structured object response using the LLM.
99    ///
100    /// # Arguments
101    ///
102    /// * `content` - The user message content
103    /// * `correlation_id` - Optional correlation ID for tracing
104    ///
105    /// # Returns
106    ///
107    /// The generated structured object
108    pub async fn generate_object<T>(
109        &self,
110        content: &str,
111        correlation_id: Option<String>,
112    ) -> Result<T>
113    where
114        T: for<'de> Deserialize<'de> + Serialize + schemars::JsonSchema + Send,
115    {
116        let messages = vec![
117            LlmMessage::system(&self.behaviour),
118            LlmMessage::user(content),
119        ];
120
121        self.broker.generate_object(&messages, None, correlation_id).await
122    }
123}
124
125#[async_trait]
126impl BaseAsyncAgent for AsyncLlmAgent {
127    async fn receive_event_async(&self, _event: Box<dyn Event>) -> Result<Vec<Box<dyn Event>>> {
128        // Default implementation returns no events
129        // Subclasses should override this to handle specific event types
130        Ok(vec![])
131    }
132}
133
134#[cfg(test)]
135mod tests {
136    use super::*;
137    use crate::llm::gateway::{CompletionConfig, StreamChunk};
138    use crate::llm::{LlmGateway, LlmGatewayResponse};
139    use futures::stream::{self, Stream};
140    use serde_json::Value;
141    use std::collections::HashMap;
142    use std::pin::Pin;
143
144    // Mock gateway for testing
145    struct MockGateway {
146        response: String,
147    }
148
149    impl MockGateway {
150        fn new(response: impl Into<String>) -> Self {
151            Self {
152                response: response.into(),
153            }
154        }
155    }
156
157    #[async_trait::async_trait]
158    impl LlmGateway for MockGateway {
159        async fn complete(
160            &self,
161            _model: &str,
162            _messages: &[LlmMessage],
163            _tools: Option<&[Box<dyn LlmTool>]>,
164            _config: &CompletionConfig,
165        ) -> Result<LlmGatewayResponse> {
166            Ok(LlmGatewayResponse {
167                content: Some(self.response.clone()),
168                object: None,
169                tool_calls: vec![],
170                thinking: None,
171                ..Default::default()
172            })
173        }
174
175        async fn complete_json(
176            &self,
177            _model: &str,
178            _messages: &[LlmMessage],
179            _schema: Value,
180            _config: &CompletionConfig,
181        ) -> Result<Value> {
182            Ok(serde_json::json!({
183                "message": self.response,
184                "confidence": 0.95
185            }))
186        }
187
188        async fn get_available_models(&self) -> Result<Vec<String>> {
189            Ok(vec!["test-model".to_string()])
190        }
191
192        async fn calculate_embeddings(
193            &self,
194            _text: &str,
195            _model: Option<&str>,
196        ) -> Result<Vec<f32>> {
197            Ok(vec![0.1, 0.2, 0.3])
198        }
199
200        fn complete_stream<'a>(
201            &'a self,
202            _model: &'a str,
203            _messages: &'a [LlmMessage],
204            _tools: Option<&'a [Box<dyn LlmTool>]>,
205            _config: &'a CompletionConfig,
206        ) -> Pin<Box<dyn Stream<Item = Result<StreamChunk>> + Send + 'a>> {
207            Box::pin(stream::iter(vec![Ok(StreamChunk::Content(self.response.clone()))]))
208        }
209    }
210
211    #[tokio::test]
212    async fn test_new_agent() {
213        let gateway = Arc::new(MockGateway::new("test response"));
214        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
215        let agent = AsyncLlmAgent::new(broker, "You are helpful", None);
216
217        assert_eq!(agent.behaviour, "You are helpful");
218        assert_eq!(agent.tools.len(), 0);
219    }
220
221    #[tokio::test]
222    async fn test_new_agent_with_tools() {
223        use crate::llm::tools::{FunctionDescriptor, ToolDescriptor};
224
225        #[derive(Clone)]
226        struct MockTool;
227        #[async_trait]
228        impl LlmTool for MockTool {
229            async fn run(
230                &self,
231                _args: &HashMap<String, Value>,
232                _ctx: &crate::llm::tools::ToolRunCtx,
233            ) -> Result<Value> {
234                Ok(serde_json::json!({"result": "ok"}))
235            }
236            fn descriptor(&self) -> ToolDescriptor {
237                ToolDescriptor {
238                    r#type: "function".to_string(),
239                    function: FunctionDescriptor {
240                        name: "mock_tool".to_string(),
241                        description: "A mock tool".to_string(),
242                        parameters: serde_json::json!({}),
243                    },
244                }
245            }
246            fn clone_box(&self) -> Box<dyn LlmTool> {
247                Box::new(self.clone())
248            }
249        }
250
251        let gateway = Arc::new(MockGateway::new("test"));
252        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
253        let tools: Vec<Box<dyn LlmTool>> = vec![Box::new(MockTool)];
254        let agent = AsyncLlmAgent::new(broker, "You are helpful", Some(tools));
255
256        assert_eq!(agent.tools.len(), 1);
257    }
258
259    #[tokio::test]
260    async fn test_add_tool() {
261        use crate::llm::tools::{FunctionDescriptor, ToolDescriptor};
262
263        #[derive(Clone)]
264        struct MockTool;
265        #[async_trait]
266        impl LlmTool for MockTool {
267            async fn run(
268                &self,
269                _args: &HashMap<String, Value>,
270                _ctx: &crate::llm::tools::ToolRunCtx,
271            ) -> Result<Value> {
272                Ok(serde_json::json!({"result": "ok"}))
273            }
274            fn descriptor(&self) -> ToolDescriptor {
275                ToolDescriptor {
276                    r#type: "function".to_string(),
277                    function: FunctionDescriptor {
278                        name: "mock_tool".to_string(),
279                        description: "A mock tool".to_string(),
280                        parameters: serde_json::json!({}),
281                    },
282                }
283            }
284            fn clone_box(&self) -> Box<dyn LlmTool> {
285                Box::new(self.clone())
286            }
287        }
288
289        let gateway = Arc::new(MockGateway::new("test"));
290        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
291        let mut agent = AsyncLlmAgent::new(broker, "You are helpful", None);
292
293        assert_eq!(agent.tools.len(), 0);
294        agent.add_tool(Box::new(MockTool));
295        assert_eq!(agent.tools.len(), 1);
296    }
297
298    #[tokio::test]
299    async fn test_generate_response() {
300        let gateway = Arc::new(MockGateway::new("Hello from LLM"));
301        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
302        let agent = AsyncLlmAgent::new(broker, "You are helpful", None);
303
304        let response = agent.generate_response("Test message", None).await.unwrap();
305
306        assert_eq!(response, "Hello from LLM");
307    }
308
309    #[tokio::test]
310    async fn test_generate_response_with_correlation_id() {
311        let gateway = Arc::new(MockGateway::new("Response"));
312        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
313        let agent = AsyncLlmAgent::new(broker, "You are helpful", None);
314
315        let response = agent
316            .generate_response("Test", Some("correlation-123".to_string()))
317            .await
318            .unwrap();
319
320        assert_eq!(response, "Response");
321    }
322
323    #[tokio::test]
324    async fn test_generate_object() {
325        #[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]
326        struct TestResponse {
327            message: String,
328            confidence: f64,
329        }
330
331        let gateway = Arc::new(MockGateway::new("Test message"));
332        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
333        let agent = AsyncLlmAgent::new(broker, "You are helpful", None);
334
335        let response: TestResponse = agent.generate_object("Generate object", None).await.unwrap();
336
337        assert_eq!(response.message, "Test message");
338        assert_eq!(response.confidence, 0.95);
339    }
340
341    #[tokio::test]
342    async fn test_receive_event_async_default() {
343        use crate::event::Event;
344        use serde::{Deserialize, Serialize};
345        use std::any::Any;
346
347        #[derive(Debug, Clone, Serialize, Deserialize)]
348        struct TestEvent {
349            source: String,
350            correlation_id: Option<String>,
351        }
352
353        impl Event for TestEvent {
354            fn source(&self) -> &str {
355                &self.source
356            }
357            fn correlation_id(&self) -> Option<&str> {
358                self.correlation_id.as_deref()
359            }
360            fn set_correlation_id(&mut self, id: String) {
361                self.correlation_id = Some(id);
362            }
363            fn as_any(&self) -> &dyn Any {
364                self
365            }
366            fn clone_box(&self) -> Box<dyn Event> {
367                Box::new(self.clone())
368            }
369        }
370
371        let gateway = Arc::new(MockGateway::new("test"));
372        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
373        let agent = AsyncLlmAgent::new(broker, "You are helpful", None);
374
375        let event = Box::new(TestEvent {
376            source: "Test".to_string(),
377            correlation_id: None,
378        }) as Box<dyn Event>;
379
380        let result = agent.receive_event_async(event).await.unwrap();
381        assert_eq!(result.len(), 0); // Default implementation returns empty
382    }
383
384    #[tokio::test]
385    async fn test_agent_with_custom_behaviour() {
386        let gateway = Arc::new(MockGateway::new("Custom response"));
387        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
388        let agent =
389            AsyncLlmAgent::new(broker, "You are a specialized agent with custom behavior", None);
390
391        assert_eq!(agent.behaviour, "You are a specialized agent with custom behavior");
392
393        let response = agent.generate_response("Test", None).await.unwrap();
394        assert_eq!(response, "Custom response");
395    }
396}