aether-agent-core 0.1.4

A minimal Rust library for building AI agents with MCP tool integration
Documentation

Aether Core

Aether Core is a Rust library for building AI agents (LLM + prompt + tools, running in a loop).

By default, agents have no system prompt and no tools — every token in the context window is yours to control. Tools come exclusively from MCP servers, so you can extend agents in any language.

Agents run in dedicated tokio tasks and communicate via async message passing. Hardware permitting, you can run hundreds of agents in a single process.

Table of Contents

Installation

Add Aether to your Cargo.toml:

[dependencies]
aether-agent-core = "0.1"

Examples

Minimal Agent (No Tools)

use aether_core::core::{AgentMessage, Prompt, UserMessage, agent};
use llm::providers::openrouter::OpenRouterProvider;
use std::io::{self, Write};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Choose your LLM. Alternatively use AnthropicProvider, LlamaCppProvider..etc
    // For this example, OPENROUTER_API_KEY needs to be set in your environment
    let llm = OpenRouterProvider::default("z-ai/glm-4.6")?;

   // 2. Create an Agent
    let (tx, mut rx, _handle) = agent(llm) // <-- Give it an LLM
        .system_prompt(Prompt::text("You are a helpful assistant.")) // <-- Give it a system prompt
        .spawn() // <-- Spawn it into a tokio task
        .await?;

    // 3. Send the agent a message
    tx.send(UserMessage::text("Explain async Rust in one paragraph"))
        .await?;

    // 4. Stream the agent's response back
    loop {
        match rx.recv().await {
            Some(AgentMessage::Text { chunk, is_complete, .. }) => {
                if !is_complete { print!("{chunk}"); io::stdout().flush()?; }
            }
            Some(AgentMessage::Done) => break,
            Some(AgentMessage::Error { message }) => { eprintln!("Error: {message}"); break; }
            _ => {}
        }
    }

    Ok(())
}

Agent with Tools and AGENTS.md system prompt

Create a mcp.json file in the current working directory:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

And create an AGENTS.md file with a system prompt:

# BotBot

You are Mr. BotBot, a kickass coding agent equipped with SOTA filesystem and web browsing tools...

And bring Mr. BotBot to life!

use aether_core::core::{AgentMessage, UserMessage, Prompt, agent};
use aether_core::mcp::{mcp, McpSpawnResult};
use llm::providers::openrouter::OpenRouterProvider;
use std::io::{self, Write};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenRouterProvider::default("z-ai/glm-4.6")?;

    // 1. Connect to MCP servers
    let McpSpawnResult {
        tool_definitions: tools,
        instructions: _,
        command_tx: mcp_tx,
        event_rx: _,
        handle: _mcp_handle,
        ..
    } = mcp()
        .from_json_files(&["mcp.json"]) // <-- Load MCP servers from one or more JSON files
        .await?
        .spawn() // <-- Spawn the MCP client into a tokio task (multiple agents can use it)
        .await?;

    // 2. Create Agent
    let (tx, mut rx, _handle) = agent(llm)
        .system_prompt(Prompt::from_globs(vec!["AGENTS.md".into()], ".".into())) // <-- Load system prompt from AGENTS.md
        .tools(mcp_tx, tools) // <-- Give the agent MCP tools
        .spawn()
        .await?;

   // Send your agent a message and stream the results back
    tx.send(UserMessage::text(
        "Read the README.md file and summarize it",
    ))
    .await?;

    loop {
        use AgentMessage::*;
        match rx.recv().await {
            Some(Text { chunk, is_complete, .. }) => {
                if !is_complete {
                    print!("{chunk}");
                    io::stdout().flush().unwrap();
                } else {
                    println!();
                }
            }
            Some(ToolCall { request, .. }) => {
                println!("\nCalling tool: {}", request.name);
            }
            Some(ToolResult { result, .. }) => {
                println!("Tool '{}' completed", result.name);
            }
            Some(ToolError { error, .. }) => {
                eprintln!("Tool '{}' failed: {}", error.name, error.error);
            }
            Some(ToolProgress { .. }) => {
                // Tool progress updates (can be used to show progress bars, etc.)
            }
            Some(Done) => {
                println!("\nAgent finished");
                break;
            }
            Some(Error { message }) => {
                eprintln!("Error: {message}");
                break;
            }
            Some(Cancelled { .. }) => {
                eprintln!("Agent cancelled");
                break;
            }
            _ => {}
            None => break,
        }
    }

    Ok(())
}

License

MIT