a2a_agents/lib.rs
1//! A2A Agents - Framework for building A2A Protocol agents
2//!
3//! This crate provides a declarative, configuration-driven framework for building
4//! agents that implement the A2A Protocol v0.3.0.
5//!
6//! # Architecture
7//!
8//! The crate is organized into three main layers:
9//!
10//! - **Core Framework** ([`core`]) - Builder, configuration, and runtime
11//! - **Plugin System** ([`traits`]) - Traits for extending agent functionality
12//! - **Utilities** ([`utils`]) - Common helpers for agent development
13//! - **Example Agents** ([`agents`]) - Reference implementations
14//!
15//! # Quick Start
16//!
17//! ```rust,ignore
18//! use a2a_agents::core::AgentBuilder;
19//!
20//! #[tokio::main]
21//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
22//! AgentBuilder::from_file("config.toml")?
23//! .with_handler(my_handler)
24//! .build_with_auto_storage()
25//! .await?
26//! .run()
27//! .await?;
28//! Ok(())
29//! }
30//! ```
31//!
32//! # Core Framework
33//!
34//! The core framework provides the essential building blocks:
35//!
36//! - [`AgentBuilder`](core::AgentBuilder) - Fluent API for agent construction
37//! - [`AgentConfig`](core::AgentConfig) - TOML-based configuration
38//! - [`AgentRuntime`](core::AgentRuntime) - Server lifecycle management
39//!
40//! # Plugin System
41//!
42//! Implement the [`AgentPlugin`](traits::AgentPlugin) trait to create agents that
43//! integrate seamlessly with the framework:
44//!
45//! ```rust
46//! use a2a_agents::traits::{AgentPlugin, SkillDefinition};
47//! use a2a_rs::port::AsyncMessageHandler;
48//! use a2a_rs::domain::{A2AError, Message, Task};
49//! use async_trait::async_trait;
50//!
51//! #[derive(Clone)]
52//! struct MyAgent;
53//!
54//! impl AgentPlugin for MyAgent {
55//! fn name(&self) -> &str { "My Agent" }
56//! fn description(&self) -> &str { "An example agent" }
57//! fn skills(&self) -> Vec<SkillDefinition> { vec![] }
58//! }
59//!
60//! #[async_trait]
61//! impl AsyncMessageHandler for MyAgent {
62//! async fn process_message(
63//! &self,
64//! _task_id: &str,
65//! _message: &Message,
66//! _session_id: Option<&str>,
67//! ) -> Result<Task, A2AError> {
68//! todo!()
69//! }
70//! }
71//! ```
72//!
73//! # Features
74//!
75//! - `default` - Includes reimbursement agent example and SQLx storage
76//! - `reimbursement-agent` - Include reimbursement agent example
77//! - `sqlx` - Enable SQLx-based task storage
78//! - `auth` - Enable authentication features (JWT, OAuth2)
79
80// Core framework modules
81pub mod core;
82pub mod traits;
83pub mod utils;
84
85// Example agent implementations
86// Note: Currently public for binaries/examples, will be private in Phase 3
87pub mod agents;
88
89// Convenience re-exports for the most commonly used types
90pub use core::{AgentBuilder, AgentConfig, AgentRuntime, BuildError, ConfigError, RuntimeError};
91pub use traits::{AgentPlugin, SkillDefinition};
92
93// Re-export the reimbursement agent for backward compatibility
94// (This will be removed in Phase 3 when agents are extracted)
95#[cfg(feature = "reimbursement-agent")]
96pub use agents::reimbursement::ReimbursementHandler;