Skip to main content

agen_macros/
lib.rs

1//! Procedural macros for declaring [`agen`](https://docs.rs/agen) tools.
2//!
3//! [`tool_registry`] expands methods marked with `#[tool]` into `agen::tool::Tool`
4//! implementations and tool definitions. Applications normally use the re-exports from
5//! `agen`; this companion crate exists so those macros can be published and versioned
6//! independently.
7
8use proc_macro::TokenStream;
9use quote::{format_ident, quote};
10use syn::{
11    Attribute, FnArg, ImplItem, ItemImpl, Lit, Meta, Pat, ReturnType, Type, parse_macro_input,
12    spanned::Spanned,
13};
14
15/// Generates tools for methods marked with `#[tool]` in an `impl` block.
16///
17/// Method doc comments become the tool description. An argument can use
18/// `#[description = "..."]` to supply its JSON Schema description.
19///
20/// ```ignore
21/// #[derive(Clone)]
22/// struct MyApp;
23///
24/// #[agen::tool_registry]
25/// impl MyApp {
26///     /// Retrieves a user by ID.
27///     #[tool]
28///     async fn get_user(
29///         &self,
30///         #[description = "The user ID"] user_id: String,
31///     ) -> Result<String, std::io::Error> {
32///         todo!()
33///     }
34/// }
35/// ```
36///
37/// This generates a `ToolGetUser` wrapper, a `GetUserArgs` schema type, and
38/// `MyApp::get_user_definition()`.
39#[proc_macro_attribute]
40pub fn tool_registry(attr: TokenStream, item: TokenStream) -> TokenStream {
41    let attr = proc_macro2::TokenStream::from(attr);
42    let impl_block = parse_macro_input!(item as ItemImpl);
43
44    expand_tool_registry(attr, impl_block)
45        .unwrap_or_else(syn::Error::into_compile_error)
46        .into()
47}
48
49fn expand_tool_registry(
50    attr: proc_macro2::TokenStream,
51    mut impl_block: ItemImpl,
52) -> syn::Result<proc_macro2::TokenStream> {
53    if !attr.is_empty() {
54        return Err(syn::Error::new(
55            attr.span(),
56            "tool_registry does not accept arguments",
57        ));
58    }
59
60    let self_ty = impl_block.self_ty.as_ref().clone();
61    let mut generated_items = Vec::new();
62
63    for item in &mut impl_block.items {
64        let ImplItem::Fn(method) = item else {
65            continue;
66        };
67
68        let tool_attrs: Vec<_> = method
69            .attrs
70            .iter()
71            .filter(|attr| attr.path().is_ident("tool"))
72            .collect();
73        if tool_attrs.len() > 1 {
74            return Err(syn::Error::new_spanned(
75                tool_attrs[1],
76                "duplicate #[tool] attribute",
77            ));
78        }
79        let Some(tool_attr) = tool_attrs.first() else {
80            continue;
81        };
82        if !matches!(tool_attr.meta, Meta::Path(_)) {
83            return Err(syn::Error::new_spanned(
84                tool_attr,
85                "#[tool] does not accept arguments",
86            ));
87        }
88
89        method.attrs.retain(|attr| !attr.path().is_ident("tool"));
90        generated_items.push(generate_tool_impl(&self_ty, method)?);
91
92        for input in &mut method.sig.inputs {
93            if let FnArg::Typed(pat_type) = input {
94                pat_type
95                    .attrs
96                    .retain(|attr| !attr.path().is_ident("description"));
97            }
98        }
99    }
100
101    Ok(quote! {
102        #impl_block
103
104        #(#generated_items)*
105    })
106}
107
108fn extract_doc_comment(attrs: &[Attribute]) -> String {
109    let mut lines = Vec::new();
110
111    for attr in attrs {
112        if attr.path().is_ident("doc")
113            && let Meta::NameValue(meta) = &attr.meta
114            && let syn::Expr::Lit(expr_lit) = &meta.value
115            && let Lit::Str(lit_str) = &expr_lit.lit
116        {
117            let line = lit_str.value();
118            let trimmed = line.strip_prefix(' ').unwrap_or(&line);
119            lines.push(trimmed.to_string());
120        }
121    }
122
123    lines.join("\n")
124}
125
126fn extract_description_attr(attrs: &[Attribute]) -> syn::Result<Option<String>> {
127    let mut description = None;
128
129    for attr in attrs
130        .iter()
131        .filter(|attr| attr.path().is_ident("description"))
132    {
133        let value = match &attr.meta {
134            Meta::NameValue(meta) => match &meta.value {
135                syn::Expr::Lit(expr_lit) => match &expr_lit.lit {
136                    Lit::Str(value) => value.value(),
137                    _ => {
138                        return Err(syn::Error::new_spanned(
139                            attr,
140                            "description must be a string literal",
141                        ));
142                    }
143                },
144                _ => {
145                    return Err(syn::Error::new_spanned(
146                        attr,
147                        "description must be a string literal",
148                    ));
149                }
150            },
151            _ => {
152                return Err(syn::Error::new_spanned(
153                    attr,
154                    "expected #[description = \"...\"]",
155                ));
156            }
157        };
158
159        if description.replace(value).is_some() {
160            return Err(syn::Error::new_spanned(
161                attr,
162                "duplicate #[description] attribute",
163            ));
164        }
165    }
166
167    Ok(description)
168}
169
170fn argument_ident(pat: &Pat) -> syn::Result<&syn::Ident> {
171    match pat {
172        Pat::Ident(pat_ident) => Ok(&pat_ident.ident),
173        _ => Err(syn::Error::new_spanned(
174            pat,
175            "tool arguments must use simple identifier patterns",
176        )),
177    }
178}
179
180fn is_tool_execution_context_type(ty: &Type) -> bool {
181    let Type::Path(path) = ty else {
182        return false;
183    };
184    path.path
185        .segments
186        .last()
187        .is_some_and(|segment| segment.ident == "ToolExecutionContext")
188}
189
190fn generate_tool_impl(
191    self_ty: &Type,
192    method: &syn::ImplItemFn,
193) -> syn::Result<proc_macro2::TokenStream> {
194    let sig = &method.sig;
195    let method_name = &sig.ident;
196    let tool_name = method_name.to_string();
197
198    let pascal_name = to_pascal_case(&method_name.to_string());
199    let tool_struct_name = format_ident!("Tool{}", pascal_name);
200    let args_struct_name = format_ident!("{}Args", pascal_name);
201    let definition_name = format_ident!("{}_definition", method_name);
202
203    let description = extract_doc_comment(&method.attrs);
204    let description = if description.is_empty() {
205        format!("Tool: {}", tool_name)
206    } else {
207        description
208    };
209
210    let method_args: Vec<_> = sig
211        .inputs
212        .iter()
213        .filter_map(|arg| match arg {
214            FnArg::Typed(pat_type) => Some(pat_type),
215            FnArg::Receiver(_) => None,
216        })
217        .collect();
218    let json_args: Vec<_> = method_args
219        .iter()
220        .copied()
221        .filter(|pat_type| !is_tool_execution_context_type(pat_type.ty.as_ref()))
222        .collect();
223
224    let arg_fields: Vec<_> = json_args
225        .iter()
226        .map(|pat_type| {
227            let field_name = argument_ident(pat_type.pat.as_ref())?;
228            let ty = &pat_type.ty;
229            let description = extract_description_attr(&pat_type.attrs)?;
230
231            Ok(if let Some(description) = description {
232                quote! {
233                    #[schemars(description = #description)]
234                    pub #field_name: #ty
235                }
236            } else {
237                quote! {
238                    pub #field_name: #ty
239                }
240            })
241        })
242        .collect::<syn::Result<_>>()?;
243
244    let call_args: Vec<_> = method_args
245        .iter()
246        .map(|pat_type| {
247            if is_tool_execution_context_type(pat_type.ty.as_ref()) {
248                Ok(quote! { ctx.clone() })
249            } else {
250                let ident = argument_ident(pat_type.pat.as_ref())?;
251                Ok(quote! { args.#ident })
252            }
253        })
254        .collect::<syn::Result<_>>()?;
255    let method_call = if call_args.is_empty() {
256        quote! { self.ctx.#method_name() }
257    } else {
258        quote! { self.ctx.#method_name(#(#call_args),*) }
259    };
260
261    let awaiter = if sig.asyncness.is_some() {
262        quote! { .await }
263    } else {
264        quote! {}
265    };
266
267    let result_handling = if is_result_type(&sig.output) {
268        quote! {
269            match result {
270                Ok(val) => Ok(format!("{:?}", val).into()),
271                Err(error) => Err(::agen::tool::ToolError::ExecutionFailed(format!("{}", error))),
272            }
273        }
274    } else {
275        quote! {
276            Ok(format!("{:?}", result).into())
277        }
278    };
279
280    let args_struct_def = quote! {
281        #[derive(
282            ::agen::__private::serde::Deserialize,
283            ::agen::__private::schemars::JsonSchema,
284        )]
285        #[serde(crate = "::agen::__private::serde")]
286        #[schemars(crate = "::agen::__private::schemars")]
287        struct #args_struct_name {
288            #(#arg_fields),*
289        }
290    };
291
292    let execute_body = if json_args.is_empty() {
293        quote! {
294            let _: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
295                .unwrap_or(#args_struct_name {});
296
297            let result = #method_call #awaiter;
298            #result_handling
299        }
300    } else {
301        quote! {
302            let args: #args_struct_name = ::agen::__private::serde_json::from_str(input_json)
303                .map_err(|error| ::agen::tool::ToolError::InvalidArgument(error.to_string()))?;
304
305            let result = #method_call #awaiter;
306            #result_handling
307        }
308    };
309
310    Ok(quote! {
311        #args_struct_def
312
313        #[derive(Clone)]
314        pub struct #tool_struct_name {
315            ctx: #self_ty,
316        }
317
318        #[::agen::__private::async_trait::async_trait]
319        impl ::agen::tool::Tool for #tool_struct_name {
320            async fn execute(
321                &self,
322                input_json: &str,
323                ctx: ::agen::tool::ToolExecutionContext,
324            ) -> Result<::agen::tool::ToolOutput, ::agen::tool::ToolError> {
325                let _ = &ctx;
326                #execute_body
327            }
328        }
329
330        impl #self_ty {
331            /// Returns a tool definition for registration with an `agen::Engine`.
332            pub fn #definition_name(&self) -> ::agen::tool::ToolDefinition {
333                let ctx = self.clone();
334                ::std::sync::Arc::new(move || {
335                    let schema = ::agen::__private::schemars::schema_for!(#args_struct_name);
336                    let meta = ::agen::tool::ToolMeta::new(#tool_name)
337                        .description(#description)
338                        .input_schema(
339                            ::agen::__private::serde_json::to_value(schema)
340                                .unwrap_or_else(|_| ::agen::__private::serde_json::json!({})),
341                        );
342                    let tool: ::std::sync::Arc<dyn ::agen::tool::Tool> =
343                        ::std::sync::Arc::new(#tool_struct_name { ctx: ctx.clone() });
344                    (meta, tool)
345                })
346            }
347        }
348    })
349}
350
351fn is_result_type(return_type: &ReturnType) -> bool {
352    match return_type {
353        ReturnType::Default => false,
354        ReturnType::Type(_, ty) => {
355            if let Type::Path(type_path) = ty.as_ref()
356                && let Some(segment) = type_path.path.segments.last()
357            {
358                return segment.ident == "Result";
359            }
360            false
361        }
362    }
363}
364
365fn to_pascal_case(s: &str) -> String {
366    s.split('_')
367        .map(|part| {
368            let mut chars = part.chars();
369            match chars.next() {
370                None => String::new(),
371                Some(first) => first.to_uppercase().chain(chars).collect(),
372            }
373        })
374        .collect()
375}
376
377/// Marker attribute interpreted by [`tool_registry`].
378#[proc_macro_attribute]
379pub fn tool(attr: TokenStream, item: TokenStream) -> TokenStream {
380    marker_attribute("tool", attr, item)
381}
382
383/// Argument description marker interpreted by [`tool_registry`].
384///
385/// Use it as `#[description = "The argument description"]` on a tool method argument.
386#[proc_macro_attribute]
387pub fn description(attr: TokenStream, item: TokenStream) -> TokenStream {
388    marker_attribute("description", attr, item)
389}
390
391fn marker_attribute(name: &str, attr: TokenStream, item: TokenStream) -> TokenStream {
392    if attr.is_empty() {
393        item
394    } else {
395        syn::Error::new(
396            proc_macro2::Span::call_site(),
397            format!("{name} is a marker interpreted by #[tool_registry]"),
398        )
399        .into_compile_error()
400        .into()
401    }
402}
403
404#[cfg(test)]
405mod tests {
406    use super::*;
407    use quote::quote;
408    use syn::parse_quote;
409
410    #[test]
411    fn rejects_tool_registry_arguments() {
412        let implementation: ItemImpl = parse_quote!(impl Registry {});
413        let error = expand_tool_registry(quote!(unexpected), implementation).unwrap_err();
414
415        assert!(error.to_string().contains("does not accept arguments"));
416    }
417
418    #[test]
419    fn rejects_duplicate_tool_markers() {
420        let implementation: ItemImpl = parse_quote! {
421            impl Registry {
422                #[tool]
423                #[tool]
424                fn inspect(&self) {}
425            }
426        };
427        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
428
429        assert!(error.to_string().contains("duplicate #[tool]"));
430    }
431
432    #[test]
433    fn rejects_invalid_description_attributes() {
434        let implementation: ItemImpl = parse_quote! {
435            impl Registry {
436                #[tool]
437                fn inspect(&self, #[description] input: String) {}
438            }
439        };
440        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
441
442        assert!(error.to_string().contains("expected #[description"));
443    }
444
445    #[test]
446    fn rejects_duplicate_description_attributes() {
447        let implementation: ItemImpl = parse_quote! {
448            impl Registry {
449                #[tool]
450                fn inspect(
451                    &self,
452                    #[description = "first"]
453                    #[description = "second"]
454                    input: String,
455                ) {}
456            }
457        };
458        let error = expand_tool_registry(quote!(), implementation).unwrap_err();
459
460        assert!(error.to_string().contains("duplicate #[description]"));
461    }
462
463    #[test]
464    fn generated_code_uses_only_agen_runtime_paths() {
465        let implementation: ItemImpl = parse_quote! {
466            impl Registry {
467                #[tool]
468                fn inspect(&self, input: String) -> Result<String, Error> {
469                    unreachable!()
470                }
471            }
472        };
473        let expanded = expand_tool_registry(quote!(), implementation)
474            .unwrap()
475            .to_string();
476
477        assert!(expanded.contains(":: agen :: tool :: Tool"));
478        assert!(expanded.contains(":: agen :: __private :: serde_json"));
479        assert!(expanded.contains(":: agen :: __private :: serde"));
480        assert!(expanded.contains(":: agen :: __private :: schemars"));
481    }
482}