Skip to main content

Crate agen

Crate agen 

Source
Expand description

§agen

agen is a provider-neutral Rust engine for streaming LLM applications that use tools. It owns the turn loop, typed conversation history, provider wire-format adapters, tool execution, interceptors, usage accounting, and cache-aware state transitions.

agen is pre-1.0. Public APIs may change between minor releases.

§Installation

[dependencies]
agen = "0.2.1"

The default feature set is intentionally empty. Enable the experimental Codex/ChatGPT authentication adapter when needed:

agen = { version = "0.2.1", features = ["codex"] }

agen requires Rust 1.86 or newer. The companion agen-macros package requires Rust 1.85 or newer.

§Quick start

Supply an implementation of LlmClient, then run a turn. The first call consumes the mutable engine and returns a cache-locked engine for later turns.

use agen::{Engine, EngineError};
use agen::llm_client::LlmClient;

async fn conversation<C: LlmClient>(client: C) -> Result<(), EngineError> {
    let output = Engine::new(client)
        .system_prompt("You are a concise assistant.")
        .run("Explain typed state in one sentence.")
        .await?;

    let mut engine = output.engine;
    let _result = engine.run("Give a Rust example.").await?;
    Ok(())
}

§Declaring tools

The tool macros are re-exported by agen; applications do not need direct dependencies on serde, schemars, serde_json, or async-trait for generated code.

use agen::tool_registry;

#[derive(Clone)]
struct Tools;

#[tool_registry]
impl Tools {
    /// Returns the supplied text.
    #[tool]
    async fn echo(
        &self,
        #[description = "Text to return"] text: String,
    ) -> Result<String, std::io::Error> {
        Ok(text)
    }
}

let definition = Tools.echo_definition();
assert_eq!(definition().0.name, "echo");

The generated API uses the canonical crate name agen. Renaming the agen dependency in Cargo.toml is not currently supported by these macros.

§Features

FeatureDefaultAdds
codexNoExperimental Codex/ChatGPT auth-file loading and token refresh support

The base crate includes provider-neutral transport and Anthropic, OpenAI-compatible, Gemini, and Ollama wire-format schemes. See llm_client for the client boundary.

§Architecture and API scope

The current public modules cover the engine, typed history, client transport/schemes, timeline events, tools, interceptors, pruning, token estimation, and usage records. Their relationships are described in Architecture; behavioral requirements are summarized in Requirements.

Low-level modules remain public in the 0.2 series because downstream Yoi components implement custom clients, event handlers, pruning policies, and tool registries against them. This surface is versioned as pre-1.0 API rather than declared stable.

§Packaging and security

The published package contains source, public documentation, curated examples, and deterministic tests/fixtures. Credentialed fixture-recording utilities are intentionally excluded. Examples that contact a provider read credentials from environment variables and never embed production credentials.

§License

Licensed under the MIT License.

Re-exports§

pub use interceptor::Interceptor;
pub use message::ContentPart;
pub use message::Item;
pub use message::Message;
pub use message::Role;
pub use tool::ToolCall;
pub use tool::ToolExecutionContext;
pub use tool::ToolOutputLimits;
pub use tool::ToolResult;
pub use usage_record::UsageRecord;

Modules§

event
Public event types for Engine layer
interceptor
Interceptor - control flow delegation for the Engine execution loop
llm_client
LLMクライアント層
providers
Optional built-in provider/backend helpers.
prune
Prune — context projection for old tool-result content.
state
Engine State
timeline
Timeline層
token_counter
Usage 履歴ベースのトークン会計(汎用部分)。
tool
Tool Definition
tool_server
usage_record
Per-LLM-request Usage measurement snapshot.

Structs§

Engine
EngineConfig
Engine configuration
EngineRunOutput
Result of Engine::run or Engine::resume.
LlmRetryNotice
Central component for managing LLM interactions
TextBlockScope
Callback scope for a text block.
ThinkingBlockScope
Callback scope for a thinking block.
ToolUseBlockScope
Callback scope for a tool use block.
ToolUseBlockStart

Enums§

EngineError
Engine errors
EngineResult
Engine execution result (status)
ToolRegistryError
Tool registration error

Type Aliases§

Message
Convenience alias

Attribute Macros§

description
Argument description marker interpreted by [tool_registry].
tool
Marker attribute interpreted by [tool_registry].
tool_registry
Generates tools for methods marked with #[tool] in an impl block.