Crate molo 

molo — an AI agent framework.

molo = Model Loop: a lightweight Rust agent framework.

Quick Start

A minimal agent needs only three things: a Provider to talk to the LLM, a Memory to manage context, and a Tool for external capabilities; the reasoning loop is built into ReActAgent, and the react_agent! macro assembles everything in one go. To self-test the loop, use FakeProvider to inject scripted replies without depending on a real API:

use molo::{react_agent, Agent, FakeProvider, FakeReply};

let mut agent = react_agent!(
    FakeProvider::new([FakeReply::Text("Hello".into())]),
    "You are a helpful assistant",
);
let answer = agent.run("Are you there?").await?;
assert_eq!(answer, "Hello");

For a real LLM, swap FakeProvider for OpenAiProvider; for retry and timeout protection, wrap it in RetryProvider; for interaction with the outside world (human approval, agent-to-agent conversation), attach a MessageChannel; to observe the reasoning process, attach an EventChannel.

Component Overview

Code is organized into domain modules, one concept per module; the top level re-exports each module’s core items, so use molo::... covers most cases without digging into module paths:

• agent — the agent interface and reasoning loop — Agent / CancellableAgent / AgentError, typed output via TypedAgent with the validator StructuredValidator, the ReActAgent assembly with the react_agent! macro, sub-agent parts (SubAgentTool / SubAgentPool), streaming output chunks and run summaries (MessageChunk / RunSummary);
• provider — LLM communication — the Provider interface, request / response / usage models (ChatRequest / ChatResponse / Usage), and implementations OpenAiProvider / RetryProvider / FakeProvider;
• tool: external capabilities — the Tool interface and tool definitions (ToolSchema), registration and execution (ToolRegistry), cross-tool shared state (SharedState), and the procedural macro for one-shot tool definitions tool;
• skill — skills — capability packages following the Agent Skills open protocol (Skill parsing / validation, SkillRegistry discovery and hot-swapping, progressive disclosure loading via LoadSkillTool);
• mcp — MCP client adapter — wiring tools exposed by external MCP servers into molo (McpClient connects and pulls, McpTool adapts tools, McpError);
• memory — context management — the Memory interface and implementations InMemoryMemory / WindowMemory (trims the oldest turns by token budget), summary compression SummarizeStrategy — old messages over budget are compressed into a single summary;
• message — the conversation message model — Message / ContentBlock / ToolCall;
• message_channel — channels for external conversation — CliMessageChannel and three more implementations (request-reply / one-way notification);
• event_channel — observation channels — subscribe to the event stream of an agent run (AgentEvent payloads).

Choosing Between Implementations

When several implementations share a responsibility, pick per scenario:

• Context: short sessions or unbounded needs use InMemoryMemory; long sessions that must stay within budget use WindowMemory;
• Talking to the LLM: for development, inject scripted replies with FakeProvider, no real API needed; for production use OpenAiProvider, wrapped in RetryProvider for retry / timeout protection;
• External conversation: use CliMessageChannel for human-terminal interaction, MpscChannel for one-to-one in-process agent conversation, BroadcastChannel / WatchChannel for one-to-many broadcast / latest-value change notifications;
• Observing the reasoning process: subscribe to agent events via BroadcastEventChannel (multiple subscribers; slow ones drop the oldest events) or MpscEventChannel (single subscriber; nothing is dropped within capacity).

Notes

• molo targets the tokio ecosystem: all async APIs require a tokio runtime; the library ships no runtime of its own, so callers bring their own (examples uniformly use #[tokio::main]);
• cancellation is cooperative and opt-in: agents that support it implement CancellableAgent; each run carries a CancellationToken that any holder may request, and the loop responds at safe points;
• tool execution failure does not abort the reasoning loop: the error text is passed back to the model, which decides what to do next.

Re-exports

pub use agent::Agent;

pub use agent::AgentConfig;

pub use agent::AgentError;

pub use agent::AgentEvent;

pub use agent::CancellableAgent;

pub use agent::MessageChunk;

pub use agent::ReActAgent;

pub use agent::ReActEvent;

pub use agent::RunSummary;

pub use agent::StructuredOutcome;

pub use agent::StructuredValidator;

pub use agent::TypedAgent;

pub use event_channel::BroadcastEventChannel;

pub use event_channel::EventChannel;

pub use event_channel::EventReceiver;

pub use event_channel::MpscEventChannel;

pub use mcp::McpClient;

pub use mcp::McpError;

pub use mcp::McpTool;

pub use memory::Budget;

pub use memory::CharTokenCounter;

pub use memory::InMemoryMemory;

pub use memory::Memory;

pub use memory::MemoryError;

pub use memory::SummarizeStrategy;

pub use memory::TokenCounter;

pub use memory::TrimResult;

pub use memory::TrimStrategy;

pub use memory::WindowDrop;

pub use memory::WindowMemory;

pub use message::ContentBlock;

pub use message::ImageContent;

pub use message::Message;

pub use message::ToolCall;

pub use message_channel::BroadcastChannel;

pub use message_channel::BroadcastReceiver;

pub use message_channel::ChannelError;

pub use message_channel::CliMessageChannel;

pub use message_channel::IncomingMessage;

pub use message_channel::MessageChannel;

pub use message_channel::MpscChannel;

pub use message_channel::WatchChannel;

pub use message_channel::WatchReceiver;

pub use provider::Backoff;

pub use provider::ChatRequest;

pub use provider::ChatResponse;

pub use provider::FakeProvider;

pub use provider::FakeReply;

pub use provider::FinishReason;

pub use provider::ModelOptions;

pub use provider::OpenAiProvider;

pub use provider::Provider;

pub use provider::ProviderError;

pub use provider::RetryPolicy;

pub use provider::RetryProvider;

pub use provider::Retryable;

pub use provider::StreamEvent;

pub use provider::StructuredOutputMode;

pub use provider::Usage;

pub use skill::AllowedTool;

pub use skill::LoadSkillTool;

pub use skill::Skill;

pub use skill::SkillError;

pub use skill::SkillRegistry;

pub use tool::MissingTools;

pub use tool::RegistryError;

pub use tool::SharedState;

pub use tool::Tool;

pub use tool::ToolError;

pub use tool::ToolRegistry;

pub use tool::ToolSchema;

Modules

agent

Agents: reasoning loops.

event_channel

Observation channels: the Agent publishes process events internally, and the environment / UI side subscribes.

mcp

MCP client adapter — brings tools exposed by external MCP servers into molo.

memory

Memory: manages the agent’s context.

message

Conversation messages.

message_channel

MessageChannel: a message transport channel between an Agent and the outside world (a human or another Agent).

provider

Provider: the interface for communicating with an LLM.

skill

Skill: capability packages following the Agent Skills open protocol (SKILL.md format).

tool

Tool: external capabilities an agent can invoke.

Macros

react_agent

Convenience assembly macro: registers a list of tools (possibly heterogeneous) with automatic boxing, creating a ToolRegistry internally. The system prompt is optional (omitted = no system prompt). Six arms:

Structs

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

Attribute Macros

async_trait

tool

Compiles an async function into a molo::tool::Tool implementation.