# Ai Agents

> One YAML = Any Agent. Declarative AI agent framework in Rust.

- **Type:** MCP server
- **Install:** `agentstack add mcp-geminik23-ai-agents`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [geminik23](https://agentstack.voostack.com/s/geminik23)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [geminik23](https://github.com/geminik23)
- **Source:** https://github.com/geminik23/ai-agents
- **Website:** https://ai-agents.rs

## Install

```sh
agentstack add mcp-geminik23-ai-agents
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AI Agents Framework

[](https://crates.io/crates/ai-agents)
[](https://docs.rs/ai-agents)
[](https://github.com/geminik23/ai-agents)
[](https://github.com/geminik23/ai-agents)

**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](https://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 before August 1, 2026. 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** - calculator, datetime, echo, file, glob, grep, file_read, file_write, file_edit, file_list, file_info, patch, git_status, git_diff, diagnostics, ask_user, todo, sleep, web_fetch, command, JSON, text, template, math, random, and HTTP; connect any MCP server for hundreds more
- **Tool scoping, policy, and context** - explicit top-level tool grants, state-level narrowing, policy bindings, effective execution limits, context-aware custom tools, read-before-write guards, command allowlists, multi-language aliases, and 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](https://ai-agents.rs/docs/concepts/) for architecture details and [Providers](https://ai-agents.rs/docs/providers/) for per-provider setup.

## Install

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

## Quick Start

### From CLI (no Rust code needed)

Create `agent.yaml`:

```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

# 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:

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

### From YAML + Rust

```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

```rust
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/](examples/) directory for more.

## CLI

```sh
# 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
```

```sh
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](https://ai-agents.rs/docs/cli/) for REPL commands, evaluation options, metadata configuration, and full reference.

## Roadmap

See the [full roadmap](https://ai-agents.rs/roadmap/) for what's shipped, what's next, and the complete feature catalog.

## Documentation

| Resource | Description |
|----------|-------------|
| [Getting Started](https://ai-agents.rs/docs/getting-started/) | Install and run your first agent in under a minute |
| [YAML Reference](https://ai-agents.rs/docs/yaml-reference/) | Complete spec for agent definition files |
| [CLI Guide](https://ai-agents.rs/docs/cli/) | All commands, flags, and REPL features |
| [Rust API](https://ai-agents.rs/docs/rust-api/) | Embedding agents in your Rust application |
| [Providers](https://ai-agents.rs/docs/providers/) | Setup for all 12 LLM providers |
| [Concepts](https://ai-agents.rs/docs/concepts/) | Architecture, lifecycle, and core ideas |
| [Examples](https://ai-agents.rs/examples/) | YAML and Rust examples for every feature |
| [API Docs](https://docs.rs/ai-agents) | Auto-generated Rust API reference |

## Key Dependencies

| Crate | Role |
|-------|------|
| [llm](https://crates.io/crates/llm) | Unified LLM provider interface (OpenAI, Anthropic, Google, Ollama, and more) |
| [rmcp](https://crates.io/crates/rmcp) | Official Rust SDK for Model Context Protocol (MCP) |
| [tokio](https://crates.io/crates/tokio) | Async runtime |
| [minijinja](https://crates.io/crates/minijinja) | Jinja2-compatible template engine for system prompts and spawner templates |
| [sqlx](https://crates.io/crates/sqlx) | SQLite storage backend (optional, `sqlite` feature) |
| [redis](https://crates.io/crates/redis) | Redis storage backend (optional, `redis-storage` feature) |

## 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](./INDEPENDENCE.md) for details.

## License

Licensed under the Apache License, Version 2.0.

See [LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [geminik23](https://github.com/geminik23)
- **Source:** [geminik23/ai-agents](https://github.com/geminik23/ai-agents)
- **License:** Apache-2.0
- **Homepage:** https://ai-agents.rs

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-geminik23-ai-agents
- Seller: https://agentstack.voostack.com/s/geminik23
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.