Skip to main content

Workspace Architecture

This page maps the crates (excluding the CLI and Serve crates) and how they compose so contributors can keep boundaries clear.

Crate Layout​

  • autoagents: Facade crate that re-exports the public surface from autoagents-core, autoagents-llm, and derive macros; holds only feature wiring and logging initialization.
  • autoagents-core: Agent engine (agent config, executors, memory, protocol/events, vector store traits, runtime abstractions). Uses ractor only on non-WASM targets; compiled out for wasm via cfg.
  • autoagents-llm: Provider-agnostic LLM traits plus concrete backend implementations (OpenAI, Anthropic, Ollama, etc.) and the LLMBuilder to configure them. Purely networking + request/response normalization, no agent logic.
  • autoagents-derive: Proc macros for #[agent], #[tool], and derive helpers (AgentOutput, ToolInput, AgentHooks) that generate glue code while keeping downstream code ergonomic.
  • autoagents-toolkit: Shared, reusable tools and MCP helpers. Feature-gated (filesystem, search, mcp) so downstream crates only pull what they need.
  • autoagents-qdrant: Vector store implementation backed by Qdrant. Implements the VectorStoreIndex trait from autoagents-core and depends on an embedding provider via SharedEmbeddingProvider.
  • Inference crates (optional): autoagents-onnx, autoagents-burn, and autoagents-mistral-rs provide local/runtime-specific inference backends. They plug into the LLM traits but are isolated to keep the core light.
  • examples/*: Runnable end-to-end examples that demonstrate wiring agents, executors, and providers; each example is its own crate to keep dependencies scoped.

Layering and Dependencies​

  • Top-level dependency direction is autoagents → (autoagents-core, autoagents-llm, autoagents-derive).
  • autoagents-core depends on autoagents-llm for message/LLM types but keeps provider-specific details out of the core execution logic.
  • autoagents-toolkit and autoagents-qdrant depend on the core traits and optionally on autoagents-llm/providers for embeddings.
  • Inference crates implement the LLM traits so they can be swapped with remote providers without changing agent code.
  • Examples pull only the crates they exercise (e.g., autoagents-qdrant for vector store examples), which keeps build times predictable and dependencies modular.

Agent/Runtime Flow (non-Serve/CLI)​

  1. Agent definition (usually via #[agent] from autoagents-derive) describes tools, output type, and hooks.
  2. Executors in autoagents-core (Basic, ReAct, direct or actor-backed) drive the conversation loop, calling into:
    • Memory providers (sliding window, etc.) from autoagents-core.
    • Tools (from autoagents-toolkit or custom example-local tools).
    • LLM providers implementing the LLMProvider traits (autoagents-llm backends or local inference crates).
  3. Optional vector store operations go through VectorStoreIndex (e.g., autoagents-qdrant).
  4. On non-WASM targets, the actor runtime (ractor) manages multi-agent orchestration; on WASM targets those pieces are cfg-gated out.

Modularity Guidelines​

  • Keep provider concerns inside autoagents-llm (or inference crates); avoid leaking HTTP/provider structs into autoagents-core.
  • Add reusable tools to autoagents-toolkit; example-specific tools should stay within their example crate.
  • Prefer feature flags on extension crates (autoagents-toolkit, autoagents-llm, inference crates) so downstream users can opt in without pulling heavy dependencies.
  • When adding new storage or provider integrations, implement the existing traits (VectorStoreIndex, EmbeddingProvider, LLMProvider) to preserve swappability and testability.