Crate aquaregia 

Aquaregia

A lightweight agent SDK for Rust: build tool-using LLM agents that run on any provider.

Features

• Tool-Using Agents: Multi-step agent loops with prepare_step hooks, stop_when, and configurable tool execution and error handling — you describe the tools, the agent runs the loop.
• Provider-Portable: The same agent (and every generate/stream call) runs on OpenAI, Anthropic, Google, and OpenAI-compatible endpoints — swap a constructor to change provider.
• Streaming & Non-Streaming: Both generate and stream APIs with consistent event handling.
• Structured Output: generate_object::<T>() deserialises responses directly into Rust types using schemars-derived JSON Schema, with provider-native support (OpenAI) and tool-use fallback (Anthropic, Google).
• Reasoning Support: First-class reasoning content extraction and streaming events.
• Multimodal Vision: Send images to vision-capable models via URL, base64, or raw bytes.
• Cancellation: All requests and agent runs support cancellation via CancellationToken.

Quick Start

use aquaregia::{GenerateTextRequest, LlmClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = LlmClient::openai_compatible().base_url("https://api.deepseek.com")
        .api_key(std::env::var("DEEPSEEK_API_KEY")?)
        .build()?;

    let out = client
        .generate(GenerateTextRequest::from_user_prompt(
            "deepseek-v4-pro",
            "Explain Rust ownership in 3 bullet points.",
        ))
        .await?;

    println!("{}", out.output_text);
    Ok(())
}

Architecture

• LlmClient: Entry point for creating provider-bound clients.
• BoundClient: Reusable client for generate, stream, and agent loops.
• Agent: Multi-step tool-using agent with configurable hooks.
• ModelAdapter: Trait for provider-specific request/response handling.
• Tool: Executable tool definitions with JSON Schema validation.

Re-exports

pub use agent::Agent;

pub use agent::AgentBuilder;

pub use client::BoundClient;

pub use client::ClientBuilder;

pub use client::LlmClient;

pub use error::Error;

pub use error::ErrorCode;

pub use tool::Tool;

pub use tool::ToolBuilder;

pub use tool::tool;

pub use types::ContentPart;

pub use types::FilePart;

pub use types::FinishReason;

pub use types::GenerateObjectResponse;

pub use types::GenerateTextRequest;

pub use types::GenerateTextResponse;

pub use types::MediaData;

pub use types::Message;

pub use types::MessageRole;

pub use types::OutputSchema;

pub use types::ReasoningPart;

pub use types::StreamEvent;

pub use types::TextPart;

pub use types::TextStream;

pub use types::ToolCall;

pub use types::ToolErrorPolicy;

pub use types::ToolResult;

pub use types::Usage;

Modules

adapters

Provider adapter traits and concrete provider implementations. Provider adapter traits and concrete provider implementations for Aquaregia.

agent

Agent runtime and builder APIs. Agent runtime and builder APIs for Aquaregia.

client

Provider-bound client types and retry behavior. Provider-bound client types and retry behavior for Aquaregia.

embed

Embedding generation types and APIs. Embedding generation types and APIs for Aquaregia.

error

Unified error types and HTTP-to-error mapping helpers. Unified error types and HTTP-to-error mapping helpers for Aquaregia.

tool

Tool definition, execution, and registry types. Tool definition and execution types for Aquaregia agents.

types

Shared request/response and event types. Shared request/response types and streaming events for Aquaregia.

Structs

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.