Agents Overview

What is an Agent?

An ArgentOS agent is a persistent AI runtime that can receive messages, reason about them, use tools to take actions, and respond. Unlike a simple chatbot, an agent has:

• Persistent memory across sessions (via MemU)
• Tool access to execute commands, browse the web, manage tasks, and more
• Multi-channel presence across Telegram, Discord, WhatsApp, and other platforms
• Autonomous capabilities via the heartbeat and task system

Core Concepts

Agent Runtime

The agent runtime is the process that manages the conversation loop with the underlying LLM (Claude, by default). It handles:

• Constructing the system prompt with identity, tools, and context
• Sending messages to the model API
• Processing tool calls and executing them
• Managing the context window (compaction when it gets too long)
• Storing and recalling memories

Sessions

Each conversation is a session. Sessions maintain context across messages and can be linked to specific channel users via pairing. See Sessions for details.

Tools

Agents have access to a set of tools that extend their capabilities beyond text generation. See the Tools section for the full reference.

Agent Configuration

Agents are configured in argent.json under the agents key:

{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 16384,
      "modelRouter": {
        "enabled": true
      }
    },
    "main": {
      "name": "Argent",
      "identity": "You are Argent, a personal AI assistant."
    }
  }
}

Lifecycle

1. Gateway starts and loads agent configuration
2. Channel message arrives and is routed to the agent
3. Agent processes the message through the agent loop
4. Response is sent back through the originating channel
5. Memory is updated with relevant information from the interaction

The agent persists as long as the gateway is running. It wakes up on incoming messages and can also be triggered by the heartbeat system.