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.
agenis 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
| Feature | Default | Adds |
|---|---|---|
codex | No | Experimental 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
- Engine
Config - Engine configuration
- Engine
RunOutput - Result of
Engine::runorEngine::resume. - LlmRetry
Notice - Central component for managing LLM interactions
- Text
Block Scope - Callback scope for a text block.
- Thinking
Block Scope - Callback scope for a thinking block.
- Tool
UseBlock Scope - Callback scope for a tool use block.
- Tool
UseBlock Start
Enums§
- Engine
Error - Engine errors
- Engine
Result - Engine execution result (status)
- Tool
Registry Error - 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 animplblock.