limit_agent/
lib.rs

1//! # limit-agent
2//!
3//! [![Crates.io](https://img.shields.io/crates/v/limit-agent.svg)](https://crates.io/crates/limit-agent)
4//! [![Docs.rs](https://docs.rs/limit-agent/badge.svg)](https://docs.rs/limit-agent)
5//! [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6//!
7//! **Agent runtime for AI applications with tool registry and Docker sandbox.**
8//!
9//! Build autonomous AI agents that can execute tools, run code in isolated
10//! containers, and maintain state across conversations.
11//!
12//! ## Features
13//!
14//! - **Tool Registry**: Define, register, and execute tools dynamically
15//! - **Docker Sandbox**: Isolated execution environment for untrusted code
16//! - **Event-driven**: Subscribe to agent lifecycle events
17//! - **State Management**: Persist and restore agent state
18//! - **LLM Integration**: Works seamlessly with `limit-llm`
19//!
20//! ## Quick Start
21//!
22//! ### Define a Custom Tool
23//!
24//! ```rust
25//! use async_trait::async_trait;
26//! use limit_agent::{Tool, AgentError};
27//! use serde_json::{json, Value};
28//!
29//! struct WeatherTool;
30//!
31//! #[async_trait]
32//! impl Tool for WeatherTool {
33//!     fn name(&self) -> &str {
34//!         "get_weather"
35//!     }
36//!     
37//!     async fn execute(&self, args: Value) -> Result<Value, AgentError> {
38//!         let location = args["location"].as_str().unwrap_or("Unknown");
39//!         // In a real implementation, call a weather API
40//!         Ok(json!({
41//!             "location": location,
42//!             "temp": 22,
43//!             "condition": "sunny"
44//!         }))
45//!     }
46//! }
47//! ```
48//!
49//! ### Register and Execute Tools
50//!
51//! ```rust
52//! use limit_agent::ToolRegistry;
53//! # use async_trait::async_trait;
54//! # use limit_agent::{Tool, AgentError};
55//! # use serde_json::{json, Value};
56//! # struct WeatherTool;
57//! # #[async_trait]
58//! # impl Tool for WeatherTool {
59//! #     fn name(&self) -> &str { "get_weather" }
60//! #     async fn execute(&self, args: Value) -> Result<Value, AgentError> {
61//! #         Ok(json!({"temp": 22}))
62//! #     }
63//! # }
64//!
65//! #[tokio::main]
66//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
67//!     let mut registry = ToolRegistry::new();
68//!     
69//!     // Register tools
70//!     registry.register(WeatherTool)?;
71//!     
72//!     // Execute a tool by name
73//!     let result = registry
74//!         .execute("get_weather", json!({ "location": "Tokyo" }))
75//!         .await?;
76//!     
77//!     println!("Weather: {:?}", result);
78//!     
79//!     Ok(())
80//! }
81//! ```
82//!
83//! ## Docker Sandbox
84//!
85//! Run untrusted code in isolated Docker containers:
86//!
87//! ```rust,no_run
88//! use limit_agent::sandbox::DockerSandbox;
89//!
90//! #[tokio::main]
91//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
92//!     // Check if Docker is available
93//!     if !DockerSandbox::check_docker_available().await {
94//!         return Err("Docker is not available".into());
95//!     }
96//!     
97//!     let sandbox = DockerSandbox::new().await?;
98//!     
99//!     // Create a container
100//!     let container = sandbox.create_container("alpine:latest").await?;
101//!     
102//!     // Start and execute
103//!     sandbox.start_container(&container).await?;
104//!     let output = sandbox.execute_in_container(&container, &["echo".into(), "hello".into()]).await?;
105//!     println!("{}", output);
106//!     
107//!     // Cleanup
108//!     sandbox.cleanup_container(&container).await;
109//!     
110//!     Ok(())
111//! }
112//! ```
113//!
114//! ## Event System
115//!
116//! Subscribe to agent lifecycle events for logging, monitoring, or debugging:
117//!
118//! ```rust
119//! use limit_agent::events::{EventBus, Event};
120//!
121//! let events = EventBus::new();
122//!
123//! events.subscribe(|event| {
124//!     match event {
125//!         Event::ToolCall { name, args, version: _ } => {
126//!             println!("Tool {} started with {:?}", name, args);
127//!         }
128//!         Event::ToolResult { output, version: _ } => {
129//!             println!("Tool completed: {}", output);
130//!         }
131//!         Event::Error { message, version: _ } => {
132//!             eprintln!("Error: {}", message);
133//!         }
134//!         _ => {}
135//!     }
136//! });
137//! ```
138//!
139//! ## Core Types
140//!
141//! | Type | Description |
142//! |------|-------------|
143//! | [`Tool`] | Trait for defining executable tools |
144//! | [`ToolRegistry`] | Registry for managing and executing tools |
145//! | [`DockerSandbox`] | Isolated execution environment |
146//! | [`StateManager`] | Persist/restore agent state |
147//! | [`EventBus`] | Event subscription system |
148
149pub mod error;
150pub mod events;
151pub mod executor;
152pub mod registry;
153pub mod sandbox;
154pub mod state;
155pub mod tool;
156
157pub use error::AgentError;
158pub use events::EventBus;
159pub use registry::ToolRegistry;
160pub use tool::{EchoTool, Tool};
limit_agent/lib.rs

limit_agent/
lib.rs
