Quick Start

This guide walks you through building your first agent with agent-air.

Setup

Create a new Rust project and add agent-air as a dependency:

cargo new my-agent && cd my-agent
cargo add agent-air

You’ll need Rust 1.75+ installed. For terminal agents, ensure your terminal supports UTF-8.

Building a Terminal Agent

The simplest way to build a terminal agent is using AgentAir with the into_tui() extension method.

Define Your Configuration

First, implement the AgentConfig trait to define your agent’s identity and defaults:

use agent_air::agent::{AgentConfig, AgentAir};
use agent_air::tui::AgentAirExt;

struct MyAgentConfig;

impl AgentConfig for MyAgentConfig {
    fn name(&self) -> &str {
        "MyAgent"
    }

    fn config_path(&self) -> &str {
        ".myagent/config.yaml"
    }

    fn default_system_prompt(&self) -> &str {
        "You are a helpful assistant."
    }

    fn log_prefix(&self) -> &str {
        "myagent"
    }
}

Create and Run the Agent

Use AgentAir::new() with your config, convert to a TUI runner with into_tui(), then call run():

fn main() -> std::io::Result<()> {
    AgentAir::new(&MyAgentConfig)?
        .into_tui()
        .run()
}

That’s it! This creates a fully functional terminal agent with the built-in TUI, theming, and all default features.

Customizing the Agent

The TuiRunner returned by into_tui() provides builder methods for customization:

use agent_air::agent::{AgentConfig, AgentAir};
use agent_air::tui::{AgentAirExt, ChatView, KeyBindings, LayoutTemplate, StatusBar};

fn main() -> std::io::Result<()> {
    let mut agent = AgentAir::new(&MyAgentConfig)?;

    // Set custom error message for unconfigured state
    agent.set_error_no_session("No API key found. Add one to ~/.myagent/config.yaml");

    // Convert to TUI runner and configure
    let mut runner = agent.into_tui();

    // Use emacs-style key bindings (default is minimal)
    runner.set_key_bindings(KeyBindings::emacs());

    // Set a custom layout
    runner.set_layout(LayoutTemplate::standard());

    // Customize the status bar
    runner.set_status_bar(
        StatusBar::new()
            .with_hint_unconfigured(" esc to exit . Add API keys to config.yaml")
    );

    // Set up a custom conversation view with welcome screen
    runner.set_conversation_factory(|| {
        Box::new(
            ChatView::new()
                .with_title("My Agent")
        )
    });

    runner.run()
}

Available Key Bindings

agent-air includes two key binding presets. The minimal preset is the default, providing simple arrow-key navigation. The emacs preset adds familiar shortcuts for developers who prefer Emacs-style editing.

PresetDescription
KeyBindings::minimal()Default. Arrow keys for navigation, Esc to quit
KeyBindings::emacs()Emacs-style: Ctrl+P/N/B/F navigation, Ctrl+A/E line start/end, Ctrl+K kill line

TuiRunner Methods

The TuiRunner provides builder methods to customize every aspect of the TUI. Call these methods after into_tui() and before run().

MethodPurpose
set_key_bindings()Set keyboard bindings preset
set_key_handler()Set custom key handler (implement KeyHandler trait)
set_layout()Set TUI layout template
set_exit_handler()Set cleanup handler for exit (implement ExitHandler trait)
set_conversation_factory()Set factory for custom chat views
set_status_bar()Set custom status bar widget
set_commands()Set custom slash commands
set_command_extension()Set shared data accessible to commands
register_widget()Register additional widgets
hide_status_bar()Hide the default status bar

Next Steps