agent_kernel/lib.rs
1//! Agent kernel crate — minimal orchestration primitives for multi-agent discussion.
2//!
3//! # Design Principles (pi-mono)
4//! - Extreme minimalism: `discuss()` is the ONLY orchestration primitive
5//! - Full trust: caller controls `rounds`, no internal policy
6//! - Observability first: `AgentEvent` is a first-class output via `mpsc::Sender`
7//! - Late binding: `Message` stays internal until provider converts at the boundary
8//!
9//! # Phase 2 additions (independent repo)
10//! - `evolution` module: `EvolutionContext` + `EvolutionRuntime` trait
11//! - `AgentEvent::Evolved` variant in `event` module
12//!
13//! # Quick Start
14//!
15//! ```rust,no_run
16//! use agent_kernel::{Agent, AgentRuntime, BoxFuture, discuss};
17//! use tokio::sync::mpsc;
18//! use tokio_util::sync::CancellationToken;
19//!
20//! struct MyRuntime;
21//!
22//! impl AgentRuntime for MyRuntime {
23//! fn respond<'a>(
24//! &'a self,
25//! agent: &'a Agent,
26//! _history: &'a [agent_kernel::Message],
27//! ) -> BoxFuture<'a, anyhow::Result<String>> {
28//! Box::pin(async move {
29//! Ok(format!("[{}] My response", agent.name))
30//! })
31//! }
32//! }
33//!
34//! #[tokio::main]
35//! async fn main() -> anyhow::Result<()> {
36//! let runtime = MyRuntime;
37//! let agents = vec![
38//! Agent { name: "alice".into(), soul_md: "You are Alice.".into(), model: "gpt-4o".into() },
39//! Agent { name: "bob".into(), soul_md: "You are Bob.".into(), model: "gpt-4o".into() },
40//! ];
41//! let (tx, mut rx) = mpsc::channel(64);
42//! let cancel = CancellationToken::new();
43//! let summary = discuss(&runtime, &agents, "What is Rust?", 2, cancel, tx).await?;
44//! while let Ok(event) = rx.try_recv() {
45//! println!("{event:?}");
46//! }
47//! println!("Summary: {summary}");
48//! Ok(())
49//! }
50//! ```
51
52pub mod agent;
53pub mod discuss;
54pub mod event;
55pub mod evolution;
56pub mod message;
57pub mod runtime;
58
59/// Boxed future used as [`AgentRuntime::respond`] return type.
60///
61/// Using an explicit `BoxFuture` instead of `async_trait` keeps the kernel
62/// dependency-free (no `async_trait` macro crate required).
63pub type BoxFuture<'a, T> = std::pin::Pin<Box<dyn std::future::Future<Output = T> + Send + 'a>>;
64
65// ── Re-exports ────────────────────────────────────────────────────────────────
66
67pub use agent::Agent;
68pub use event::AgentEvent;
69pub use evolution::{EvolutionContext, EvolutionRuntime};
70pub use message::{Message, Role};
71pub use runtime::AgentRuntime;
72pub use discuss::discuss;