Skip to main content

mojentic/llm/tools/
tool_wrapper.rs

1use crate::error::Result;
2use crate::llm::broker::LlmBroker;
3use crate::llm::models::{LlmMessage, MessageRole};
4use crate::llm::tools::{FunctionDescriptor, LlmTool, ToolDescriptor};
5use async_trait::async_trait;
6use serde_json::{json, Value};
7use std::collections::HashMap;
8use std::sync::Arc;
9
10/// Wraps an agent (broker + tools + behaviour) as an LlmTool
11///
12/// This allows agents to be used as tools by other agents (delegation pattern).
13/// The tool's descriptor has a single "input" parameter (string).
14/// When run, it creates initial messages from the agent's behaviour, appends the input,
15/// and calls the agent's broker.
16pub struct ToolWrapper {
17    broker: Arc<LlmBroker>,
18    tools: Vec<Box<dyn LlmTool>>,
19    behaviour: String,
20    name: String,
21    description: String,
22}
23
24impl ToolWrapper {
25    /// Create a new ToolWrapper
26    ///
27    /// # Arguments
28    /// * `broker` - The LLM broker for this agent
29    /// * `tools` - The tools available to this agent
30    /// * `behaviour` - The system message defining the agent's behaviour
31    /// * `name` - The name of this tool (how other agents will call it)
32    /// * `description` - Description of what this agent/tool does
33    pub fn new(
34        broker: Arc<LlmBroker>,
35        tools: Vec<Box<dyn LlmTool>>,
36        behaviour: impl Into<String>,
37        name: impl Into<String>,
38        description: impl Into<String>,
39    ) -> Self {
40        Self {
41            broker,
42            tools,
43            behaviour: behaviour.into(),
44            name: name.into(),
45            description: description.into(),
46        }
47    }
48
49    /// Create initial messages with the agent's behaviour
50    fn create_initial_messages(&self) -> Vec<LlmMessage> {
51        vec![LlmMessage {
52            role: MessageRole::System,
53            content: Some(self.behaviour.clone()),
54            tool_calls: None,
55            image_paths: None,
56            reasoning_content: None,
57        }]
58    }
59}
60
61#[async_trait]
62impl LlmTool for ToolWrapper {
63    async fn run(
64        &self,
65        args: &HashMap<String, Value>,
66        _ctx: &crate::llm::tools::ToolRunCtx,
67    ) -> Result<Value> {
68        // Extract input from arguments
69        let input = args.get("input").and_then(|v| v.as_str()).ok_or_else(|| {
70            crate::error::MojenticError::ToolError("Missing 'input' parameter".to_string())
71        })?;
72
73        // Create initial messages with behaviour
74        let mut messages = self.create_initial_messages();
75
76        // Append the user input
77        messages.push(LlmMessage {
78            role: MessageRole::User,
79            content: Some(input.to_string()),
80            tool_calls: None,
81            image_paths: None,
82            reasoning_content: None,
83        });
84
85        let response = self.broker.generate(&messages, Some(&self.tools), None, None).await?;
86
87        Ok(json!(response))
88    }
89
90    fn descriptor(&self) -> ToolDescriptor {
91        ToolDescriptor {
92            r#type: "function".to_string(),
93            function: FunctionDescriptor {
94                name: self.name.clone(),
95                description: self.description.clone(),
96                parameters: json!({
97                    "type": "object",
98                    "properties": {
99                        "input": {
100                            "type": "string",
101                            "description": "Instructions for this agent."
102                        }
103                    },
104                    "required": ["input"],
105                    "additionalProperties": false
106                }),
107            },
108        }
109    }
110
111    fn clone_box(&self) -> Box<dyn LlmTool> {
112        Box::new(ToolWrapper {
113            broker: self.broker.clone(),
114            tools: self.tools.iter().map(|t| t.clone_box()).collect(),
115            behaviour: self.behaviour.clone(),
116            name: self.name.clone(),
117            description: self.description.clone(),
118        })
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125    use crate::llm::gateway::{CompletionConfig, LlmGateway, StreamChunk};
126    use crate::llm::models::LlmGatewayResponse;
127    use futures::stream::{self, Stream};
128    use std::pin::Pin;
129
130    // Mock gateway for testing
131    struct MockGateway {
132        expected_behaviour: String,
133        response: String,
134    }
135
136    impl MockGateway {
137        fn new(expected_behaviour: String, response: String) -> Self {
138            Self {
139                expected_behaviour,
140                response,
141            }
142        }
143    }
144
145    #[async_trait::async_trait]
146    impl LlmGateway for MockGateway {
147        async fn complete(
148            &self,
149            _model: &str,
150            messages: &[LlmMessage],
151            _tools: Option<&[Box<dyn LlmTool>]>,
152            _config: &CompletionConfig,
153        ) -> Result<LlmGatewayResponse> {
154            // Verify that the first message is the system message with behaviour
155            assert!(messages.len() >= 2, "Expected at least 2 messages (system + user)");
156            assert_eq!(messages[0].role, MessageRole::System, "First message should be system");
157            assert_eq!(
158                messages[0].content.as_ref().unwrap(),
159                &self.expected_behaviour,
160                "System message should match behaviour"
161            );
162
163            Ok(LlmGatewayResponse {
164                content: Some(self.response.clone()),
165                object: None,
166                tool_calls: vec![],
167                thinking: None,
168                ..Default::default()
169            })
170        }
171
172        async fn complete_json(
173            &self,
174            _model: &str,
175            _messages: &[LlmMessage],
176            _schema: Value,
177            _config: &CompletionConfig,
178        ) -> Result<Value> {
179            Ok(json!({}))
180        }
181
182        async fn get_available_models(&self) -> Result<Vec<String>> {
183            Ok(vec![])
184        }
185
186        async fn calculate_embeddings(
187            &self,
188            _text: &str,
189            _model: Option<&str>,
190        ) -> Result<Vec<f32>> {
191            Ok(vec![])
192        }
193
194        fn complete_stream<'a>(
195            &'a self,
196            _model: &'a str,
197            _messages: &'a [LlmMessage],
198            _tools: Option<&'a [Box<dyn LlmTool>]>,
199            _config: &'a CompletionConfig,
200        ) -> Pin<Box<dyn Stream<Item = Result<StreamChunk>> + Send + 'a>> {
201            Box::pin(stream::iter(vec![]))
202        }
203    }
204
205    #[tokio::test]
206    async fn test_tool_wrapper_descriptor() {
207        let gateway = Arc::new(MockGateway::new(
208            "You are a test agent".to_string(),
209            "test response".to_string(),
210        ));
211        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
212        let tools: Vec<Box<dyn LlmTool>> = vec![];
213
214        let wrapper = ToolWrapper::new(
215            broker,
216            tools,
217            "You are a test agent",
218            "test_agent",
219            "A test agent for unit testing",
220        );
221
222        let descriptor = wrapper.descriptor();
223
224        assert_eq!(descriptor.r#type, "function");
225        assert_eq!(descriptor.function.name, "test_agent");
226        assert_eq!(descriptor.function.description, "A test agent for unit testing");
227
228        let params = descriptor.function.parameters;
229        assert_eq!(params["type"], "object");
230        assert!(params["properties"]["input"].is_object());
231        assert_eq!(params["properties"]["input"]["type"], "string");
232        assert_eq!(params["properties"]["input"]["description"], "Instructions for this agent.");
233        assert_eq!(params["required"], json!(["input"]));
234        assert_eq!(params["additionalProperties"], false);
235    }
236
237    #[tokio::test]
238    async fn test_tool_wrapper_execution() {
239        let gateway = Arc::new(MockGateway::new(
240            "You are a helpful assistant".to_string(),
241            "I can help with that!".to_string(),
242        ));
243        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
244        let tools: Vec<Box<dyn LlmTool>> = vec![];
245
246        let wrapper = ToolWrapper::new(
247            broker,
248            tools,
249            "You are a helpful assistant",
250            "assistant",
251            "A helpful assistant",
252        );
253
254        let mut args = HashMap::new();
255        args.insert("input".to_string(), json!("Help me with something"));
256
257        let result = wrapper.run(&args, &crate::llm::tools::ToolRunCtx::default()).await.unwrap();
258
259        // Result should be a JSON string value
260        assert_eq!(result, json!("I can help with that!"));
261    }
262
263    #[tokio::test]
264    async fn test_tool_wrapper_missing_input() {
265        let gateway =
266            Arc::new(MockGateway::new("You are a test agent".to_string(), "test".to_string()));
267        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
268        let tools: Vec<Box<dyn LlmTool>> = vec![];
269
270        let wrapper =
271            ToolWrapper::new(broker, tools, "You are a test agent", "test_agent", "A test agent");
272
273        let args = HashMap::new();
274        let result = wrapper.run(&args, &crate::llm::tools::ToolRunCtx::default()).await;
275
276        assert!(result.is_err());
277        match result {
278            Err(crate::error::MojenticError::ToolError(message)) => {
279                assert_eq!(message, "Missing 'input' parameter");
280            }
281            _ => panic!("Expected ToolError"),
282        }
283    }
284
285    #[tokio::test]
286    async fn test_tool_wrapper_with_tools() {
287        // Mock tool for the wrapped agent
288        struct MockTool;
289
290        #[async_trait]
291
292        impl LlmTool for MockTool {
293            async fn run(
294                &self,
295                _args: &HashMap<String, Value>,
296                _ctx: &crate::llm::tools::ToolRunCtx,
297            ) -> Result<Value> {
298                Ok(json!({"result": "tool executed"}))
299            }
300
301            fn descriptor(&self) -> ToolDescriptor {
302                ToolDescriptor {
303                    r#type: "function".to_string(),
304                    function: FunctionDescriptor {
305                        name: "mock_tool".to_string(),
306                        description: "A mock tool".to_string(),
307                        parameters: json!({}),
308                    },
309                }
310            }
311
312            fn clone_box(&self) -> Box<dyn LlmTool> {
313                Box::new(MockTool)
314            }
315        }
316
317        let gateway = Arc::new(MockGateway::new(
318            "You are an agent with tools".to_string(),
319            "Task completed using tools".to_string(),
320        ));
321        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
322        let tools: Vec<Box<dyn LlmTool>> = vec![Box::new(MockTool)];
323
324        let wrapper = ToolWrapper::new(
325            broker,
326            tools,
327            "You are an agent with tools",
328            "tool_agent",
329            "An agent that has access to tools",
330        );
331
332        let mut args = HashMap::new();
333        args.insert("input".to_string(), json!("Use your tools"));
334
335        let result = wrapper.run(&args, &crate::llm::tools::ToolRunCtx::default()).await.unwrap();
336
337        assert_eq!(result, json!("Task completed using tools"));
338    }
339
340    #[tokio::test]
341    async fn test_tool_wrapper_matches() {
342        let gateway = Arc::new(MockGateway::new("test".to_string(), "test".to_string()));
343        let broker = Arc::new(LlmBroker::new("test-model", gateway, None));
344        let tools: Vec<Box<dyn LlmTool>> = vec![];
345
346        let wrapper =
347            ToolWrapper::new(broker, tools, "You are a test agent", "my_agent", "A test agent");
348
349        assert!(wrapper.matches("my_agent"));
350        assert!(!wrapper.matches("other_agent"));
351    }
352}