What is Riverbeam

Riverbeam is a set of Rust crates for running AI agents behind an API. You register agents, send them an invoke request, and Riverbeam runs the request through one pipeline: quota check, session and run tracking, a security check, memory and knowledge retrieval, model selection, the agent itself, streaming, and persistence.

Riverbeam builds on Riverbase. The command and query surface is a Riverbase domain, errors are RiverbaseError values with BEM-* codes, and workers distribute tasks over NATS with riverbase_task.

src/main.rs

use beam_core::{BeamConfig, RiverBeam};
use beam_types::InvokeRequest;
use serde_json::json;
use uuid::Uuid;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let beam = RiverBeam::new(BeamConfig::default());
    beam.register_echo_agent("assistant");

    let request: InvokeRequest = serde_json::from_value(json!({
        "agent_name": "assistant",
        "session_id": Uuid::new_v4(),
        "content": [{"type": "text", "text": "hello"}]
    }))?;

    let result = beam.invoke_result(request).await?;
    println!("{}", result.content[0].text.as_deref().unwrap_or_default()); // "Echo: hello"
    Ok(())
}

Architecture

In production, an API process and one or more worker processes share NATS and Postgres. The API authorizes each command and forwards it to a worker. The worker runs the pipeline and publishes stream frames that the API relays to the client over server-sent events (SSE).

You can also run everything in one process: LocalWorkerClient calls the worker directly, and in-memory transports and stores replace NATS and Postgres. The quick start uses that setup, and the tutorial grows it step by step into the split production setup.

What you get

Capability	Crate	Page
Invoke pipeline and BEM-* error catalogue	beam_core	Invoke pipeline
Agents, tool loop, skills, OpenAI-compatible client	beam_agents	Agents, tools and skills
Retrieval (RAG): embedders, vector stores, ingest	beam_knowledge	Knowledge
Scoped memory and model routing	beam_memory, beam_routing	Memory and model routing
Stream frames over memory, broadcast, or NATS	beam_stream	Streaming
Security rules, usage quotas, audit events	beam_security, beam_usage, beam_audit	Security, usage and audit
Worker RPC, domain commands, authorization	beam_worker, beam_domain	Worker and API
Sessions, runs, messages, human approval	beam_store	Sessions and human approval
Path-jailed workspace with git	beam_sandbox	Agents, tools and skills
Realtime audio turns	beam_audio	Realtime audio

The full list, with feature flags, is in Crates.

Status

Riverbeam is at version 0.1.0. The public repository, riverbase-io/riverbeam, holds the library crates, the migration, and tests. It does not include an example application. Pages call out behaviour that is not finished yet under Current limitations.