car_multi/lib.rs
1//! Multi-agent coordination for Common Agent Runtime.
2//!
3//! Provides six coordination patterns:
4//!
5//! | Pattern | Description |
6//! |---------|-------------|
7//! | **Swarm** | N agents on the same problem (parallel, sequential, or debate) |
8//! | **Pipeline** | Linear chain — each agent's output feeds the next |
9//! | **Supervisor** | One agent reviews workers, iterates until approval |
10//! | **Delegator** | Main agent spawns specialists mid-run via a tool |
11//! | **MapReduce** | Fan-out to N mappers, reduce into a single result |
12//! | **Vote** | N agents answer independently, majority wins |
13//!
14//! ## How agents communicate
15//!
16//! Agents communicate through three mechanisms:
17//!
18//! 1. **Shared state** — all agents in a coordination group share the same
19//! `Arc<StateStore>` and `Arc<EventLog>` via `SharedInfra`. Agents can read
20//! each other's state writes.
21//!
22//! 2. **Task enrichment** — orchestrators pass prior agents' outputs into the
23//! next agent's task prompt (e.g., sequential swarm, supervisor feedback).
24//!
25//! 3. **Mailbox** — async channel-based messaging for real-time inter-agent
26//! communication during execution.
27//!
28//! ## The AgentRunner trait
29//!
30//! Since the runtime doesn't own the model, the caller implements `AgentRunner`
31//! to drive the model loop. `car-multi` orchestrates *when* and *how* agents run;
32//! the caller decides *what* each agent does.
33//!
34//! ```rust,ignore
35//! use car_multi::{AgentRunner, AgentSpec, AgentOutput, Mailbox, MultiError};
36//! use car_engine::Runtime;
37//!
38//! struct MyRunner { /* OpenAI client, etc. */ }
39//!
40//! #[async_trait::async_trait]
41//! impl AgentRunner for MyRunner {
42//! async fn run(
43//! &self,
44//! spec: &AgentSpec,
45//! task: &str,
46//! runtime: &Runtime,
47//! mailbox: &Mailbox,
48//! ) -> Result<AgentOutput, MultiError> {
49//! // 1. Call your LLM with spec.system_prompt + task
50//! // 2. Parse response into ActionProposal
51//! // 3. runtime.execute(&proposal).await
52//! // 4. Return AgentOutput
53//! todo!()
54//! }
55//! }
56//! ```
57
58pub mod error;
59pub mod mailbox;
60pub mod patterns;
61pub mod runner;
62pub mod shared;
63pub mod types;
64
65// Re-exports for convenience
66pub use error::MultiError;
67pub use mailbox::Mailbox;
68pub use runner::AgentRunner;
69pub use shared::SharedInfra;
70pub use types::{AgentOutput, AgentSpec, Message, MessageKind};
71
72pub use patterns::delegator::{Delegator, DelegatorResult};
73pub use patterns::map_reduce::{MapReduce, MapReduceResult};
74pub use patterns::pipeline::{Pipeline, PipelineResult};
75pub use patterns::supervisor::{Supervisor, SupervisorResult};
76pub use patterns::swarm::{Swarm, SwarmMode, SwarmResult};
77pub use patterns::fleet::{Fleet, FleetResult};
78pub use patterns::vote::{Vote, VoteResult};