AI Agents Framework

One YAML = Any Agent.

A Rust framework for building AI agents from a single YAML specification. No code required for common use cases.

ai-agents.rs - Documentation, guides, and examples

• YAML-first behavior - common agent behavior is declarative, with Rust host integrations for custom extensions
• Language-agnostic semantics - intent, extraction, validation via LLM (no regex)
• Layered overrides - global → agent → state → skill → turn
• Explicit safety controls - fail-closed tool grants, policy, HITL approvals, error recovery
• Extensible - custom LLMs, tools, memory, storage, hooks

Status: 1.0.5 - Stable v1 surfaces follow SemVer within the documented support and operational boundaries.

Features

• Multi-LLM with fallback - 12 providers (OpenAI, Anthropic, Google, Ollama, DeepSeek, Groq, Mistral, Cohere, xAI, Phind, OpenRouter, any OpenAI-compatible); named aliases (default, router); auto-fallback on failure
• State machine + skills - hierarchical states, LLM-evaluated transitions, guard-based routing, entry/exit actions, reusable multi-step skills
• Built-in tools + MCP - 30 canonical built-in IDs: calculator, echo, datetime, json, random, file, glob, grep, file_read, file_write, file_edit, patch, copy_path, move_path, delete_path, file_list, file_info, git_status, git_diff, diagnostics, ask_user, todo, sleep, web_fetch, web_search, command, text, template, math, and http; connect any MCP server for hundreds more
• Tool scoping, selection, policy, and context - explicit top-level grants, state-level narrowing, opt-in auto/required/specific/none tool choice, policy bindings, review modes for filesystem mutation, post-approval final authorization, atomic rate admission, conservative mutation locking, read-before-write guards, command allowlists, and context-aware custom tools
• Input/output process pipeline - deterministic normalization and formatting plus optional LLM-backed detection, extraction, sanitization, validation, and transformation
• Dynamic context - runtime, file, HTTP, env, and callback sources with Jinja2 templates in prompts
• Memory stack - CompactingMemory and token budgeting; file and Redis snapshot persistence; SQLite snapshots, session metadata/filtering/cleanup, actor facts, and relationship memory
• Agent persona - structured identity, traits, goals, secrets, evolution, and reusable templates
• Dynamic agent spawning + multi-agent systems - fail-closed child admission, bounded managed capacity, optional shared LLMs and namespaced storage, agent registry, actor-aware messaging, and router/pipeline/concurrent/group chat/handoff orchestration; active nested spawners are rejected in v1
• CLI + TUI - interactive REPL, ratatui terminal UI, streaming with authoritative final responses, context injection, and actor/relationship inspection
• Reasoning, reflection & disambiguation - chain-of-thought, ReAct, plan-and-execute, self-evaluation, ambiguity detection, and clarification
• Evaluation, safety, control & observability - YAML scenario evals with assertions/judges, runtime latency optimization, speculative branch execution, error recovery with backoff, tool security, HITL approvals, and privacy-safe latency/token/cost tracing with JSON/CSV/Prometheus exports
• Extensible via traits - LLMProvider, Memory, Tool, ApprovalHandler, Summarizer, AgentHooks, ToolProvider; custom LLM providers remain source-compatible and can opt into native tool requests through additive methods

Ordinary model-callable tools are fail-closed through explicit grants. Optional tool security adds path, command, domain, approval, timeout, and result-limit enforcement. These controls are not an OS sandbox; hosts remain responsible for deployment isolation, filesystem ownership, network egress, credentials, custom integrations, and provider-internal I/O.

v1 Scope and Support

The v1 scope includes YAML-first construction, blocking and streaming chat, strict specs, state, skills, process, context, explicit tool grants and final authorization, memory, capability-aware storage, facts and relationships, spawning and orchestration, evaluation, observability, provider adapters, CLI/TUI, and opt-in runtime optimization.

• Stable: builder and blocking chat, strict YAML, state/skills/process/context, built-in tool authorization, and in-memory/compacting memory follow normal v1 SemVer; compatibility changes are recorded in the changelog.
• Supported: streaming, evaluation and observability, provider adapters and MCP, persona, file and SQLite storage, facts and relationships, spawning and orchestration, and runtime optimization are production-usable within their documented operational boundaries.
• Experimental: Redis is snapshot-only for v1, and Noop storage provides no persistence. Both may receive compatibility changes in a minor release with release notes, but may not silently lose data or bypass safety checks.
• Future Work: the Generalized Autonomy Runner, retrieval/evidence/RAG, generalized background scheduling, and Python bindings are not shipped v1 contracts.

See Concepts for architecture details and Providers for per-provider setup.

Install

The published crates and CLI require Rust 1.88 or newer.

[dependencies]
ai-agents = "1.0"

Quick Start

From CLI (no Rust code needed)

Create agent.yaml:

# agent.yaml
name: MyAgent
system_prompt: "You are a helpful assistant."
llm:
  provider: openai
  model: gpt-5.4-nano

# For any OpenAI-compatible server:
# llm:
#   provider: openai-compatible
#   model: qwen3:8b
#   base_url: http://localhost:11434/v1

# Fixed framework fields are strict; provider-specific extra params are allowed inside llm configs.
# Example for OpenAI reasoning-capable models:
# llms:
#   default:
#     provider: openai
#     model: gpt-5.4-mini
#     reasoning_effort: low
# llm:
#   default: default

Run it:

cargo run -p ai-agents-cli -- run agent.yaml

From YAML + Rust

use ai_agents::{Agent, AgentBuilder};

#[tokio::main]
async fn main() -> ai_agents::Result<()> {
    let agent = AgentBuilder::from_yaml_file("agent.yaml")?
        .auto_configure_llms()?
        .auto_configure_features()?
        .auto_configure_mcp().await?
        .auto_configure_spawner().await?
        .build()?;

    let response = agent.chat("Hello!").await?;
    println!("{}", response.content);
    Ok(())
}

This is the same builder chain used by the CLI. auto_configure_mcp() and auto_configure_spawner() are safe to keep in the chain even when the YAML does not use MCP tools or a spawner: section.

From Rust API

use ai_agents::{AgentBuilder, UnifiedLLMProvider, ProviderType};
use std::sync::Arc;

#[tokio::main]
async fn main() -> ai_agents::Result<()> {
    let llm = UnifiedLLMProvider::from_env(ProviderType::OpenAI, "gpt-5.4-nano")?;

    let agent = AgentBuilder::new()
        .system_prompt("You are a helpful assistant.")
        .llm(Arc::new(llm))
        .build()?;

    let response = agent.chat("Hello!").await?;
    println!("{}", response.content);
    Ok(())
}

See the examples/ directory for more.

CLI

# Install from crates.io
cargo install ai-agents-cli

# Or run directly from source
cargo run -p ai-agents-cli -- run agent.yaml

ai-agents-cli run agent.yaml                          # interactive REPL
ai-agents-cli run agent.yaml --stream --show-tools     # stream tokens, show tool calls
ai-agents-cli run agent.yaml --show-state --show-timing # show state transitions and timing
ai-agents-cli validate agent.yaml                      # check YAML without starting
ai-agents-cli eval --agent agent.yaml --scenarios eval/suite.yaml --output eval_results/

Use eval to run YAML or JSONL scenario suites with strict fail-closed assertions, exact replay, synchronized record fixtures, optional LLM judge checks, retries, strict default redaction, JSON/Markdown/JUnit outputs, and observability reports when enabled. Real and record modes require explicit --real-llm or --record authorization.

See the CLI Guide for REPL commands, evaluation options, metadata configuration, and full reference.

Roadmap

See the full roadmap for what's shipped, what's next, and the complete feature catalog.

Documentation

| CLI Guide | All commands, flags, and REPL features | | Rust API | Embedding agents in your Rust application | | Providers | Setup for all 12 LLM providers | | Concepts | Architecture, lifecycle, and core ideas | | Examples | YAML and Rust examples for every feature | | API Docs | Auto-generated Rust API reference |

Key Dependencies

Independence Notice

This repository is an independent open-source project maintained by the author in a personal capacity.

It is not an official product or offering of any employer, and no employer owns or governs this project.

See INDEPENDENCE.md for details.

License

Licensed under the Apache License, Version 2.0.

See LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0.