Agent Architecture

Architecture Overview

The agent sits at the center of ArgentOS, bridging the gateway (which handles channels and the dashboard) with the Claude API and tool execution.

Channels ──> Gateway ──> Agent Runtime ──> Claude API
                │              │
                │              ├──> Tool Execution
                │              ├──> Memory (MemU)
                │              └──> Task System
                │
                └──> Dashboard (WebSocket)

Components

Gateway

The gateway is the always-on WebSocket server that receives messages from all channels and the dashboard. It routes incoming messages to the agent runtime and broadcasts responses back. See Gateway for details.

Agent Runtime

The agent runtime (src/agents/) manages the interaction with the LLM:

1. System prompt assembly -- Combines identity, soul, tool definitions, bootstrap memory, and injected context
2. Message handling -- Receives normalized messages from the gateway
3. API calls -- Sends requests to the Claude API (or other providers via the model router)
4. Tool execution -- Processes tool use blocks returned by the model
5. Response streaming -- Streams responses back to the gateway

Model Router

Before the API call, the model router scores the complexity of the request and routes it to the appropriate model tier. See Model Router.

Memory Integration

The agent has built-in memory_store and memory_recall tools that write to and read from MemU, the persistent SQLite memory database. Memory context is also injected into the system prompt at boot time. See Memory.

Tool System

Tools are defined as JSON schemas and registered with the agent runtime. When the model returns a tool_use block, the runtime executes the corresponding tool handler and returns the result. See Tools.

Message Flow (Detailed)

1. User sends "What's on my task list?" on Telegram
2. Telegram channel driver normalizes the message
3. Gateway routes it to the agent's session
4. Agent assembles the full prompt with system context
5. Model router scores complexity -> routes to Haiku (simple query)
6. Haiku returns a tool_use block for tasks_list
7. Agent runtime executes the tool, gets task data
8. Tool result is sent back to the model
9. Model generates a natural language response
10. Response is streamed back through the gateway to Telegram

Configuration Reference

The agent runtime is configured via argent.json:

{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 16384,
      "temperature": 1,
      "systemPrompt": {
        "identity": true,
        "soul": true,
        "tools": true,
        "bootstrap": true
      }
    }
  }
}