Overview

Aquaregia is a Rust SDK for applications that need an LLM to do work, not just return one completion.

The common shape is:

1. choose a provider client
2. bind it to a model with client.agent(model)
3. add instructions and tools
4. run the agent, stream it, or inspect the full transcript

use aquaregia::providers::openai;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = openai::Client::from_env()?
        .agent("gpt-5.5")
        .instructions("You are concise.")
        .build()?;

    let response = agent
        .prompt("Explain Rust ownership in 3 bullet points.")
        .await?;

    println!("{response}");
    Ok(())
}

When to use Aquaregia

Use Aquaregia when your application needs one of these workflows:

• a model-bound assistant with stable instructions
• a tool-using loop where the model can call your Rust code
• streaming output for a CLI, chat UI, or debug panel
• structured data returned as Rust types
• direct model requests for application-managed conversations
• multimodal prompts and embeddings for retrieval
• the same high-level code running across multiple providers

For one-off lower-level calls, provider clients also expose generate(...), stream(...), generate_object::<T>(...), stream_object::<T>(...), and embed(...).

The mental model

An agent is a loop:

1. send the current messages and tool schemas to the model
2. receive text and optional tool calls
3. execute requested tools
4. send tool results back to the model
5. stop when the model returns a final answer or your stopping rule fires

Aquaregia owns that loop. Your code owns the tools, model choice, stopping policy, and how to display the result.

Choose a path

Start with the guide that matches what you are building: