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

• Declarative behavior - everything in YAML, not code
• Language-agnostic semantics - intent, extraction, validation via LLM (no regex)
• Layered overrides - global → agent → state → skill → turn
• Safety by default - tool policies, HITL approvals, error recovery
• Extensible - custom LLMs, tools, memory, storage, hooks

Status: 1.0.0-rc.15 — Under active development. Stable v1.0.0 is planned for release by mid-July 2026 at the latest. APIs and YAML schema may change between minor versions.

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 - datetime, JSON, HTTP, file, text, template, math, calculator, random, echo; connect any MCP server for hundreds more
• Tool scoping & conditions - explicit top-level tool grants, state-level narrowing, context/state/time/semantic conditions, multi-language aliases, safe parallel execution
• Input/output process pipeline - normalize, detect, extract, sanitize, validate, transform, format - all LLM-based, works across languages
• Dynamic context - runtime, file, HTTP, env, and callback sources with Jinja2 templates in prompts
• Memory stack - CompactingMemory, token budgeting, SQLite/Redis/file persistence, session metadata, actor facts, and relationship memory
• Agent persona - structured identity, traits, goals, secrets, evolution, and reusable templates
• Multi-agent systems - dynamic agent spawning, agent registry, actor-aware inter-agent messaging, and router/pipeline/concurrent/group chat/handoff orchestration
• CLI + TUI - interactive REPL, ratatui terminal UI, streaming, 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

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

Install

[dependencies]
ai-agents = "1.0.0-rc.15"

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-4.1-nano

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

# Provider-specific extra params are also allowed.
# 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-4.1-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 --version 1.0.0-rc.15

# 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 mock/replay/record fixtures, rule-based assertions, optional LLM judge checks, retries, strict default redaction, JSON/Markdown/JUnit outputs, and observability reports when enabled.

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

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.