Skip to main content

​
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.

​
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 message

“What’s on my task list?” on Telegram
2

Normalize

Telegram channel driver normalizes the message
3

Route

Gateway routes it to the agent’s session
4

Assemble prompt

Agent assembles the full prompt with system context
5

Model routing

Model router scores complexity -> routes to Haiku (simple query)
6

Tool call

Haiku returns a tool_use block for tasks_list
7

Execute tool

Agent runtime executes the tool, gets task data
8

Return result

Tool result is sent back to the model
9

Generate response

Model generates a natural language response
10

Deliver

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
      }
    }
  }
}