Crate appam 

Rust agent orchestration library for tool-using, long-horizon, traceable AI systems.

Appam is designed for agent workloads where the hard parts are operational: repeated tool use across multiple turns, streaming UX, session persistence, trace capture, and provider portability. The shared runtime stays provider agnostic while the provider modules own wire-format quirks, auth, retry, and streaming details.

What Appam Gives You

• Rust-first agent construction through AgentBuilder, RuntimeAgent, and the shortcut constructors in agent::quick
• typed and untyped tool definitions via Tool, AsyncTool, ToolRegistry, tool, and Schema
• streaming-first execution through agent::streaming::StreamEvent, agent::streaming_builder::StreamBuilder, and built-in consumers
• durable session history through SessionHistory
• portable LLM routing across Anthropic, OpenAI, OpenAI Codex, OpenRouter, Vertex, Azure, and Bedrock via LlmProvider and DynamicLlmClient

Recommended Entry Points

Use Agent::quick when you want the smallest working setup:

use appam::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let agent = Agent::quick(
        "anthropic/claude-sonnet-4-5",
        "You are a concise Rust assistant.",
        vec![],
    )?;

    agent
        .stream("Explain ownership in Rust in three sentences.")
        .on_content(|text| print!("{text}"))
        .run()
        .await?;

    println!();
    Ok(())
}

Use AgentBuilder when you need explicit runtime control:

use appam::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    let agent = AgentBuilder::new("assistant")
        .provider(LlmProvider::OpenAI)
        .model("openai/gpt-5.4")
        .system_prompt("You are a careful assistant. Use tools before guessing.")
        .with_tool(Arc::new(EchoTool))
        .enable_history()
        .build()?;

    agent.run("Say hello via the echo tool.").await?;
    Ok(())
}

Use TomlAgent when configuration lives on disk and needs to be extended with Rust tools at runtime:

use appam::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<()> {
    let agent = TomlAgent::from_file("agent.toml")?
        .with_additional_tool(Arc::new(CustomTool));

    agent.run("Use the custom tool if it helps.").await?;
    Ok(())
}

Architecture

Appam keeps the crate split along subsystem boundaries:

• agent owns runtime orchestration, continuation logic, stream events, and session history
• tools owns schemas, execution traits, managed state, and runtime lookup
• llm owns provider-neutral message types plus provider-specific clients
• config owns global configuration, env overrides, and builder APIs
• logging owns tracing setup and persisted session logs

Security and Operational Notes

• Tool calls are model output and must be treated as untrusted input.
• Managed state access fails closed when state was not registered.
• The legacy web API surface remains intentionally disabled; the trace visualizer helpers in web remain available.
• Provider-specific secrets are never meant to be logged or embedded in trace artifacts.

Docs.rs Navigation

If you are new to the crate, the most useful pages are usually:

• prelude for the ergonomic import surface
• AgentBuilder and RuntimeAgent for programmatic agents
• Tool and AsyncTool for tool authoring
• tool and Schema for macro-driven tool definitions
• StreamBuilder for closure-based streaming
• SessionHistory for durable sessions

Re-exports

pub use agent::history::SessionHistory;

pub use agent::Agent;

pub use agent::AgentBuilder;

pub use agent::RuntimeAgent;

pub use agent::Session;

pub use agent::TomlAgent;

pub use config::load_config_from_env;

pub use config::load_global_config;

pub use config::AgentConfigBuilder;

pub use config::AppConfig;

pub use config::AppConfigBuilder;

pub use config::HistoryConfig;

pub use config::LogFormat;

pub use config::LoggingConfig;

pub use config::TraceFormat;

pub use llm::DynamicLlmClient;

pub use llm::LlmClient;

pub use llm::LlmProvider;

pub use llm::UnifiedMessage;

pub use llm::UnifiedTool;

pub use llm::UnifiedToolCall;

pub use tools::AsyncTool;

pub use tools::SessionState;

pub use tools::State;

pub use tools::Tool;

pub use tools::ToolConcurrency;

pub use tools::ToolContext;

pub use tools::ToolRegistry;

Modules

agent

Core agent abstractions, runtime entry points, and session metadata.

config

Global configuration types and precedence helpers.

http

Shared HTTP utilities.

llm

Provider-neutral LLM types plus provider-specific client modules.

logging

Structured runtime logging plus persisted session transcripts.

prelude

Convenient import surface for the most common Appam workflows.

tools

Tool traits, managed state, and runtime execution helpers.

web

Legacy web helpers and the trace visualizer server.

Attribute Macros

async_trait

tool

Attribute macro for defining Appam tools from ordinary Rust functions.

Derive Macros

Schema

Derive macro for generating JSON schemas with simplified description attributes.