How the Agent Works

The Thumper-Run AI agent is a reasoning engine that reads, thinks, and acts on your behalf.

Think of the agent as a junior developer with a specific set of tools. It can read files, search code, install apps, check GPU status, and edit configurations — but it always asks before making changes. It reasons step-by-step, showing its thought process so you can follow along.

The agent uses the ReAct (Reason + Act) framework. Each turn follows a 6-step handshake:

Example ReAct Trace

Thought: The user wants to install a chatbot. I should check what's available.
Action: list_apps
Action Input: {"query": "chatbot", "tag": "llm"}
Observation: Found 3 apps: open-webui (4.5/5), sillytavern (4.3/5)
Thought: Open WebUI is highest rated. I'll install it.
Action: install_app
Action Input: {"source_url": "https://github.com/open-webui/open-webui"}
[Waiting for user confirmation...]
[User approved]
Observation: Installation complete. App registered as "open-webui".
Thought: Installation successful. I should tell the user.
Final Answer: I've installed Open WebUI. You can launch it from the dashboard.

Safety rails: each reasoning step has a 60-second timeout. If the LLM produces malformed output, the executor retries once via step_with_retry with format hints. Context is trimmed at 80% utilization to prevent overflow.

Tools are registered in a HashMap<String, Arc<dyn Tool>> by the ToolDispatcher. Each tool implements the Tool trait:

pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    fn requires_confirmation(&self) -> bool;
    async fn execute(&self, args: Value, ctx: ToolContext) -> ToolResult;
}

6 Tool Factories

The dispatcher is built with a chain of factory methods, each adding a group of related tools:

ToolResult

Every tool returns a ToolResult with: success (bool), output (string), artifacts (optional files/data), duration_ms, and error (optional). The result becomes the Observation in the ReAct trace.

ToolContext

Each tool execution receives a ToolContext with: session_id, project_root, working_directory, sandboxed: true, and max_execution_seconds. This scopes the tool's access to the project directory.

The agent supports 5 LLM backends via the BackendKind enum. All support streaming responses.

The system prompt is assembled from multiple sources, each with a priority level. Higher priority sections are placed first and are more resistant to context trimming.

Tool Guidelines

The platform knowledge section includes these core guidelines that shape agent behavior:

- If the user asks about a file, READ it first (don't guess contents)
- If the user asks to change something, READ current state THEN EDIT
- If the user asks about apps or models, LIST the relevant directory first
- NEVER claim you can't access files — use file_read and search_code tools
- ALWAYS show the user what you found before giving advice

For implementation details, these are the key source files: