Agent Module

Overview

The agent module orchestrates the core functionality of IronClaw:

Message routing from channels
Job scheduling and execution
Tool invocation with safety guardrails
Self-repair for stuck jobs
Proactive heartbeat execution
Routine-based scheduled and reactive jobs
Turn-based session management with undo
Context compaction for long conversations

Core Types

Agent

The main agent orchestrator that processes incoming messages and manages execution.

user_id

String

User identifier for the agent session

session

Session

Current session state with threads and turns

workspace

Workspace

Persistent memory storage for the agent

tools

ToolRegistry

Available tools for the agent to use

Example

use ironclaw::agent::{Agent, AgentDeps};

let deps = AgentDeps {
    llm: Arc::new(llm_provider),
    workspace: Arc::new(workspace),
    tools: Arc::new(tool_registry),
};

let agent = Agent::new("user_123", deps);

Session

A session contains one or more threads representing conversations with the agent.

Uuid

Unique session identifier

user_id

String

User who owns this session

active_thread

Option<Uuid>

Currently active thread ID

threads

HashMap<Uuid, Thread>

All threads in this session

auto_approved_tools

HashSet<String>

Tools that have been auto-approved for this session

Methods

new

fn(user_id: impl Into<String>) -> Self

Create a new session for a user

create_thread

fn(&mut self) -> &mut Thread

Create a new thread in this session and make it active

active_thread

fn(&self) -> Option<&Thread>

Get the currently active thread

is_tool_auto_approved

fn(&self, tool_name: &str) -> bool

Check if a tool has been auto-approved

auto_approve_tool

fn(&mut self, tool_name: impl Into<String>)

Add a tool to the auto-approved set

Example

use ironclaw::agent::Session;

let mut session = Session::new("user_123");
let thread = session.create_thread();

// Auto-approve a tool for this session
session.auto_approve_tool("file_read");
assert!(session.is_tool_auto_approved("file_read"));

Thread

A thread represents a conversation sequence with turns (request/response pairs).

Uuid

Unique thread identifier

session_id

Uuid

Parent session ID

turns

Vec<Turn>

Conversation history as turns

state

ThreadState

Current state (Active, Interrupted, Completed)

Turn

A single request/response pair in a conversation.

Uuid

Unique turn identifier

user_message

String

User’s input message

assistant_message

Option<String>

Agent’s response (None if turn incomplete)

tool_calls

Vec<ToolCall>

Tool invocations made during this turn

state

TurnState

Current state (Pending, InProgress, Completed, Failed)

Routine

A scheduled or reactive job that runs automatically.

Uuid

Unique routine identifier

name

String

Human-readable routine name

trigger

Trigger

When this routine should execute

action

RoutineAction

What the routine should do

Trigger Types

Cron

String

Execute on a cron schedule (e.g., “0 9 * * *”)

Interval

Duration

Execute every N seconds/minutes/hours

Event

String

Execute when a specific event occurs

Example

use ironclaw::agent::{Routine, RoutineAction, Trigger};
use std::time::Duration;

let routine = Routine {
    id: Uuid::new_v4(),
    name: "Daily standup reminder".to_string(),
    trigger: Trigger::Cron("0 9 * * 1-5".to_string()),
    action: RoutineAction::SendMessage {
        content: "Time for standup!".to_string(),
    },
};

ContextCompactor

Compacts conversation history to save context window space.

compact

async fn(thread: &Thread) -> Result<CompactionResult>

Compact a thread’s conversation history by summarizing old turns

should_compact

fn(thread: &Thread) -> bool

Check if a thread should be compacted based on size

CompactionResult

original_turns

usize

Number of turns before compaction

compacted_turns

usize

Number of turns after compaction

summary

String

Summary of compacted content

tokens_saved

u32

Approximate tokens saved by compaction

Example

use ironclaw::agent::ContextCompactor;

let compactor = ContextCompactor::new(llm_provider);
if compactor.should_compact(&thread) {
    let result = compactor.compact(&thread).await?;
    println!("Saved {} tokens", result.tokens_saved);
}

UndoManager

Manages checkpoints and undo operations for sessions.

create_checkpoint

fn(&mut self, session: &Session) -> Checkpoint

Create a checkpoint of the current session state

restore_checkpoint

fn(&mut self, checkpoint_id: Uuid) -> Result<Session>

Restore session to a previous checkpoint

list_checkpoints

fn(&self) -> Vec<Checkpoint>

List all available checkpoints

Example

use ironclaw::agent::UndoManager;

let mut undo_mgr = UndoManager::new();

// Create checkpoint before risky operation
let checkpoint = undo_mgr.create_checkpoint(&session);

// If something goes wrong, restore
if needs_undo {
    let restored_session = undo_mgr.restore_checkpoint(checkpoint.id)?;
}

SelfRepair

Detects and repairs stuck jobs and broken tools.

detect_stuck_jobs

async fn() -> Vec<StuckJob>

Find jobs that have been running too long

repair

async fn(task: RepairTask) -> Result<RepairResult>

Attempt to repair a stuck job or broken tool

RepairTask Types

StuckJob

{ job_id: Uuid, reason: String }

A job that needs to be unstuck

BrokenTool

{ tool_name: String, error: ToolError }

A tool that failed and needs repair

Example

use ironclaw::agent::SelfRepair;

let repair = SelfRepair::new();
let stuck = repair.detect_stuck_jobs().await;

for job in stuck {
    let result = repair.repair(RepairTask::StuckJob {
        job_id: job.id,
        reason: "Timeout".to_string(),
    }).await?;
}

Workspace Module

Persistent memory storage for agents

Tools Module

Extensible tool system for agent capabilities

LLM Module

Language model integration and providers

Core Modules

Built-in Tools

Overview

Core Types

Agent

Example

Session

Methods

Example

Thread

Turn

Routine

Trigger Types

Example

ContextCompactor

CompactionResult

Example

UndoManager

Example

SelfRepair

RepairTask Types

Example

Workspace Module

Tools Module

LLM Module

Build docs developers (and LLMs) love

Core Modules

Built-in Tools

Documentation Index

​Overview

​Core Types

​Agent

​Example

​Session

​Methods

​Example

​Thread

​Turn

​Routine

​Trigger Types

​Example

​ContextCompactor

​CompactionResult

​Example

​UndoManager

​Example

​SelfRepair

​RepairTask Types

​Example

​Related Modules

Workspace Module

Tools Module

LLM Module

Build docs developers (and LLMs) love

Overview

Core Types

Agent

Example

Session

Methods

Example

Thread

Turn

Routine

Trigger Types

Example

ContextCompactor

CompactionResult

Example

UndoManager

Example

SelfRepair

RepairTask Types

Example

Related Modules