How adamstrojek/rust-agentai works
Project type and purpose
• This is a Rust workspace hosting an open-source library (crate) called AgentAI, plus a companion agentai-macros crate.
File structure
• Top-level files and dirs:
• .github – CI/CD workflows (crate publishing, tests).
• Cargo.toml – workspace definition pointing at two crates under crates/.
• crates/agentai/ – primary library.
• crates/agentai-macros/ – procedural macro crate for deriving tooling boilerplate.
• scripts/ – helper scripts to run examples.
• Inside crates/agentai/:
• src/lib.rs – public API entry.
• src/agent.rs – core Agent struct and workflow.
• src/tool/ – built-in implementations: buildin.rs, web.rs, mcp.rs + ToolBox trait.
• src/structured_output.rs – parsing and enforcing structured responses.
• examples/ – demonstration code for various use cases.
• agentai-macros provides the #[toolbox] macro to auto-generate code to wire tools into agents.
README for additional insights
• Confirms that AgentAI uses the GenAI crate under the hood to connect to many LLM providers.
• Highlights feature flags (MCP, macros, built-in tools, web tools).
• Shows sample usage: instantiate Agent, call .run(...) with model id, prompt, optional toolset.
a. Main components to represent:
• AgentAI Library
• Agent Core (the Agent struct & workflow manager)
• Structured Output module
• ToolBox Trait (extension point)
• Tools (plug-in modules)
• Built-in Tools (e.g., web scraping, string utilities)
• Web Tools (HTTP client wrappers)
• MCP Client (Model-Context-Protocol server connector)
• Custom Tools (user-defined via #[toolbox] macro)
• agentai-macros crate (codegen for ToolBox implementations)
• GenAI dependency (abstract LLM provider interface)
• External LLM Providers (OpenAI, Anthropic, Gemini, Ollama, etc.)
• Examples & CI (demonstrate usage, test workflows)
b. Relationships and interactions:
• Agent Core invokes GenAI to send prompts to an LLM provider.
• GenAI routes to an External LLM API (e.g., OpenAI).
• Agent Core consults its configured ToolBox implementations when a step requires a tool.
• Tool modules implement the ToolBox trait; autogenerated code from agentai-macros wires them in.
• Structured Output module validates or deserializes LLM responses into typed Rust structures.
• Examples import the agentai crate, assemble an Agent with tools, and demonstrate end-to-end runs.
c. Architectural patterns and principles:
• Modular plugin pattern: Tools implement a ToolBox trait, decoupling agent logic from concrete tool implementations.
• Separation of concerns:
• Agent management vs. tooling vs. output parsing vs. codegen.
• Workspace structure in Cargo: multi-crate design for core vs. macros, keeping procedural macro code separate.
• Feature flags drive conditional compilation of tool modules.
d. Technologies, frameworks, libraries:
• Rust/Cargo workspace
• GenAI crate for LLM abstraction
• Tokio (async runtime, implied by usage)
• Serde (for structured output parsing)
• Procedural macros (agentai-macros)
Detailed capturing of essential elements
• Break out:
• Agent workflow manager
• Structured output parser
• ToolBox trait (interface)
• Each tool module category
• Macros crate (codegen)
• GenAI + external provider cluster
• Feature-flag toggles as optional modules.
• Blue for core crates
• Green for compile-time macros
• Orange for external services
• Gray for examples/CI