Skip to main content

tools/
tools.rs

1//! A tool round trip by hand, without the agent loop.
2//!
3//! `cargo run --example tools -- anthropic`
4//!
5//! [`modelbridge::agent`] does all of this for you and you should usually use
6//! it. This is the primitive underneath, for when you want to own the loop:
7//! ask, receive tool calls, run them, hand the results back as real
8//! conversation turns, and get an answer. The same code runs unchanged against
9//! Responses, Anthropic Messages, and Chat Completions.
10
11use modelbridge::{Client, Message, Request, ToolCall, ToolResult, ToolSchema};
12use serde_json::json;
13
14fn schemas() -> Vec<ToolSchema> {
15    vec![ToolSchema::new(
16        "distance_km",
17        "Straight-line distance between two cities, in kilometres.",
18        json!({
19            "type": "object",
20            "properties": {
21                "from": { "type": "string" },
22                "to": { "type": "string" },
23            },
24            "required": ["from", "to"],
25        }),
26    )]
27}
28
29/// Stands in for whatever your tool actually does. Returning `Err` is how you
30/// tell the model a call failed in a way it could work around.
31fn run(call: &ToolCall) -> Result<String, String> {
32    match call.name.as_str() {
33        "distance_km" => {
34            let from = call.arg("from").ok_or("`from` is required")?;
35            let to = call.arg("to").ok_or("`to` is required")?;
36            Ok(format!("{from} to {to}: 1,213 km"))
37        }
38        other => Err(format!("no tool named `{other}`")),
39    }
40}
41
42fn main() -> Result<(), String> {
43    let provider = std::env::args().nth(1).unwrap_or_else(|| "openai".into());
44    let client = Client::default_for(&provider)?;
45
46    let question = "How far is Lisbon from Paris, and how long would that take at 90 km/h?";
47    let mut conversation = vec![Message::user(question)];
48
49    // Turn one: offer the tools and see what comes back.
50    let first = client.complete(
51        &Request::new("Use the tools for anything factual. Answer in one sentence.")
52            .messages(conversation.clone())
53            .tools(schemas())
54            .max_output_tokens(400),
55    )?;
56
57    if first.tool_calls.is_empty() {
58        println!("{}", first.text);
59        return Ok(());
60    }
61
62    // `as_message` is the assistant turn that made those calls, ids and all.
63    // Skipping it, or replaying the calls as prose, is what makes a hand-rolled
64    // loop confuse the model on turn two.
65    conversation.push(first.as_message());
66
67    let mut results = Vec::new();
68    for (index, call) in first.tool_calls.iter().enumerate() {
69        eprintln!("[calling {}({})]", call.name, call.args);
70        results.push(match run(call) {
71            Ok(output) => ToolResult::new(call, index, output),
72            Err(message) => ToolResult::failure(call, index, message),
73        });
74    }
75    conversation.push(Message::tool_results(results));
76
77    // Turn two: same conversation, results attached, no tools offered so it
78    // has to answer.
79    let second = client.complete(
80        &Request::new("Use the tools for anything factual. Answer in one sentence.")
81            .messages(conversation)
82            .max_output_tokens(400),
83    )?;
84
85    println!("{}", second.text);
86    let usage = first.usage + second.usage;
87    eprintln!(
88        "2 turns, {} tokens, about ${:.4}",
89        usage.total(),
90        usage.dollars()
91    );
92    Ok(())
93}