> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Architecture

> How the ArgentOS agent runtime connects the gateway, Claude API, tools, and memory.

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

```mermaid theme={null}
graph LR
    A[Channels] --> B[Gateway]
    B --> C[Agent Runtime]
    C --> D[Claude API]
    C --> E[Tool Execution]
    C --> F["Memory (MemU)"]
    C --> G[Task System]
    B --> H["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](/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](/models/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](/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](/tools).

## Message Flow (Detailed)

<Steps>
  <Step title="User sends message">
    "What's on my task list?" on Telegram
  </Step>

  <Step title="Normalize">
    Telegram channel driver normalizes the message
  </Step>

  <Step title="Route">
    Gateway routes it to the agent's session
  </Step>

  <Step title="Assemble prompt">
    Agent assembles the full prompt with system context
  </Step>

  <Step title="Model routing">
    Model router scores complexity -> routes to Haiku (simple query)
  </Step>

  <Step title="Tool call">
    Haiku returns a `tool_use` block for `tasks_list`
  </Step>

  <Step title="Execute tool">
    Agent runtime executes the tool, gets task data
  </Step>

  <Step title="Return result">
    Tool result is sent back to the model
  </Step>

  <Step title="Generate response">
    Model generates a natural language response
  </Step>

  <Step title="Deliver">
    Response is streamed back through the gateway to Telegram
  </Step>
</Steps>

## Configuration Reference

The agent runtime is configured via `argent.json`:

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