Skip to main content

Crate agnt_macros

Crate agnt_macros 

Source
Expand description

§agnt-macros

Proc-macros for the agnt agent runtime.

§#[tool] attribute

Apply #[agnt_macros::tool] (or #[agnt::tool] when re-exported from the flagship crate) to a free function to generate a unit struct plus a TypedTool impl.

ⓘ
use agnt_macros::tool;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct AddArgs { a: i64, b: i64 }
#[derive(Serialize)]
struct AddOut { sum: i64 }

/// Add two integers and return their sum.
#[tool]
fn add(args: AddArgs) -> Result<AddOut, String> {
    Ok(AddOut { sum: args.a + args.b })
}

// Generates:
//   pub struct Add;
//   impl agnt_core::TypedTool for Add { ... NAME = "add" ... }

§Requirements on the annotated function

  • Exactly one argument whose type becomes TypedTool::Args.
  • Return type must be Result<Output, Error>.
  • A doc comment is strongly recommended — it becomes the tool description the model sees. If absent, the function name is used as a fallback.

§⚠️ Known limitations (v0.3.x)

schema() is a placeholder — the model sees no field information. The generated TypedTool::schema returns the literal value {"type": "object"} with no properties, no required, no field types. Consequences:

  • The model cannot see what arguments your tool accepts, so it will guess field names from the description alone.
  • A wrong guess produces a serde_json deserialization error that is surfaced as the tool result; the model then has to re-plan from the error message.
  • For any non-trivial tool, the macro currently reduces ergonomics versus hand-writing a TypedTool impl where you control schema() and can emit a real JSON Schema.

This will be fixed in v0.4 behind an opt-in #[tool(schema = schemars)] attribute that wires the annotated Args type through schemars to produce a real JSON Schema. Until then, prefer a hand-written TypedTool impl for any tool whose arguments are non-obvious from the description alone.

§Other limitations

  • Only free functions are supported; methods and closures are not.
  • The function is left in place unchanged, so you can still call it directly. The generated struct’s TypedTool::call simply forwards.

Attribute Macros§

tool
Generate a [TypedTool] impl from a free function.