autumn_plugin_agent/
lib.rs

1//! Provider-agnostic, always-on LLM agent harness for Autumn.
2//!
3//! `autumn-plugin-agent` equips an Autumn app with tool-calling agents that
4//! speak to OpenAI-compatible endpoints (OpenAI, Ollama, vLLM)
5//! or the Anthropic Messages API — no heavyweight LLM SDK required.
6//!
7//! Beyond one-shot runs, the crate has the primitives always-on agents
8//! share: persisted sessions with compaction, bounded memory, skills,
9//! approval gates with resumable state, lifecycle hooks, a loop guard,
10//! heartbeats on Autumn's scheduler, agent-scheduled follow-ups, and a
11//! delivery channel.
12//!
13//! # Quick start
14//!
15//! ```rust,ignore
16//! use autumn_plugin_agent::plugin::{AgentHandle, AgentPlugin};
17//! use autumn_plugin_agent::{FnTool, AgentError};
18//! use autumn_web::prelude::*;
19//! use std::sync::Arc;
20//!
21//! async fn get_weather(input: serde_json::Value) -> Result<serde_json::Value, AgentError> {
22//!     Ok(serde_json::json!({"temp_f": 72}))
23//! }
24//!
25//! #[autumn_web::main]
26//! async fn main() {
27//!     let weather = FnTool::new(
28//!         "get_weather",
29//!         "Current weather for a city.",
30//!         serde_json::json!({"type": "object",
31//!             "properties": {"city": {"type": "string"}},
32//!             "required": ["city"]}),
33//!         get_weather,
34//!     )
35//!     .shared();
36//!
37//!     autumn_web::app()
38//!         .plugin(AgentPlugin::new().tool(Arc::clone(&weather)))
39//!         .run()
40//!         .await;
41//! }
42//! ```
43//!
44//! ```toml
45//! # autumn.toml
46//! [agent]
47//! provider = "openai-compatible"
48//! model = "gpt-4o-mini"
49//! ```
50//!
51//! ```sh
52//! export AGENT_API_KEY="sk-..."
53//! ```
54//!
55//! # Module map
56//!
57//! | Module | Contents |
58//! |--------|----------|
59//! | [`config`] | Layered `[agent]` configuration; secrets stay in the env |
60//! | [`error`] | `AgentError` + `ErrorKind` + HTTP status mapping |
61//! | [`client`] | `LlmClient` trait and both provider implementations |
62//! | [`tools`] | `Tool` trait and the handler-function adapter |
63//! | [`agent`] | The agent loop, budgets, approvals, and `AgentRuntime` |
64//! | [`hooks`] | Lifecycle hooks around model and tool calls |
65//! | [`policy`] | Per-call allow / ask / deny decisions |
66//! | [`loop_guard`] | Repeated-call detection |
67//! | [`session`] | Persisted transcripts and compaction |
68//! | [`memory`] | Bounded memory blocks and the `memory` tool |
69//! | [`skills`] | `SKILL.md` skills and the `load_skill` tool |
70//! | [`delegate`] | Subagents as tools |
71//! | [`proactive`] | Heartbeats, follow-ups, and delivery |
72//! | [`jobs`] | The `agent_run` / `agent_resume` background jobs |
73//! | [`ids`] | `RunId` and `SessionId` |
74//! | [`plugin`] | `AgentPlugin` registration and the `AgentHandle` extractor |
75//! | [`health`] | Provider health indicator for `/actuator/health` |
76
77#![forbid(unsafe_code)]
78#![deny(
79    clippy::unwrap_used,
80    clippy::expect_used,
81    clippy::panic,
82    clippy::todo,
83    clippy::unimplemented
84)]
85
86pub mod agent;
87pub mod client;
88pub mod config;
89pub mod delegate;
90pub mod error;
91pub mod health;
92pub mod hooks;
93pub mod ids;
94pub mod jobs;
95pub mod loop_guard;
96pub mod memory;
97pub mod plugin;
98pub mod policy;
99pub mod proactive;
100pub mod session;
101pub mod skills;
102pub mod tools;
103
104#[cfg(test)]
105mod test_support;
106
107pub use agent::{
108    Agent, AgentOutcome, AgentRuntime, AgentTurn, Approval, ApprovalDecision, BudgetKind,
109    PendingCall, PendingStatus, RunState,
110};
111pub use client::{
112    AnthropicClient, ChatMessage, ChatRequest, ChatResponse, ChatRole, ContentPart, LlmClient,
113    OpenAiCompatibleClient, StopReason, TokenUsage, ToolDefinition, client_from_config,
114};
115pub use config::{AgentConfig, ProviderKind};
116pub use delegate::AgentTool;
117pub use error::{AgentError, ErrorKind};
118pub use health::AgentHealthIndicator;
119pub use hooks::{AgentHooks, HookAction, RunInfo, ToolOutput};
120pub use ids::{RunId, SessionId};
121pub use jobs::{
122    AgentResumeArgs, AgentRunArgs, RunOrigin, enqueue_agent_resume, enqueue_agent_resume_tracked,
123    enqueue_agent_run, enqueue_agent_run_in, enqueue_agent_run_tracked,
124};
125pub use loop_guard::LoopGuard;
126pub use memory::{InMemoryMemoryStore, MemoryBlock, MemoryOp, MemoryScope, MemoryStore};
127pub use plugin::{AgentHandle, AgentPlugin};
128pub use policy::{AllowAll, Rule, Strictest, ToolDecision, ToolPolicy, ToolRules};
129pub use proactive::{Delivery, HEARTBEAT_OK, Heartbeat, LogDelivery, Report, ReportSource};
130pub use session::{Compaction, InMemorySessionStore, SessionStore};
131pub use skills::Skill;
132pub use tools::{FnTool, Tool, ToolCall, ToolContext, ToolEffect};
autumn_plugin_agent/lib.rs

autumn_plugin_agent/
lib.rs
