llmy_agent/lib.rs
1//! Building blocks for tool-using LLM agents.
2//!
3//! `llmy-agent` provides the small, opinionated primitives that higher-level
4//! crates (such as `llmy-harness`) compose into a complete agent loop:
5//!
6//! * [`mod@tool`] — the [`Tool`] / [`ToolDyn`] traits and the
7//! [`tool::ToolBox`] registry, used to expose Rust functions to a model and
8//! to dispatch tool calls back to them.
9//! * [`agent`] — the [`StepResult`] type that summarises a single turn of an
10//! agent loop (the model either stopped with a final assistant message or
11//! issued tool calls that need to be executed before the next step).
12//!
13//! # Defining a tool
14//!
15//! Implementing [`Tool`] by hand is straightforward, but the
16//! [`llmy_agent_derive::tool`] attribute macro (re-exported here as
17//! [`tool`](macro@tool), and also reachable through the umbrella crate as
18//! `llmy::agent::tool`) generates the boilerplate for you:
19//!
20//! ```ignore
21//! use llmy_agent::{LLMYError, tool};
22//! use schemars::JsonSchema;
23//! use serde::Deserialize;
24//!
25//! #[derive(Deserialize, JsonSchema)]
26//! struct AddArgs { a: i64, b: i64 }
27//!
28//! #[derive(Clone, Debug)]
29//! #[tool(
30//! description = "Add two integers",
31//! arguments = AddArgs,
32//! invoke = run,
33//! )]
34//! struct AddTool;
35//!
36//! impl AddTool {
37//! async fn run(&self, args: AddArgs) -> Result<String, LLMYError> {
38//! Ok((args.a + args.b).to_string())
39//! }
40//! }
41//! ```
42//!
43//! Tools can then be collected into a [`tool::ToolBox`], rendered as OpenAI
44//! tool descriptors with [`tool::ToolBox::openai_objects`], and dispatched
45//! against incoming `tool_calls` with the various `invoke_*` methods.
46//!
47//! # Re-exports
48//!
49//! For convenience the most commonly used items are re-exported at the crate
50//! root: [`StepResult`], [`Tool`], [`ToolDyn`], [`LLMYError`] and the
51//! [`tool`](macro@tool) attribute macro.
52
53pub mod agent;
54/// MCP server support — serve a [`tool::ToolBox`] over stdio or HTTP.
55pub mod mcp;
56pub mod tool;
57
58pub use agent::StepResult;
59pub use llmy_agent_derive::tool;
60pub use llmy_types::error::LLMYError;
61pub use tool::{Tool, ToolDyn};
62
63/// Re-export of the [`rmcp`] crate for MCP protocol types.
64pub mod rcmp {
65 pub use rmcp::*;
66}