Agent Runtime

Agent Runtime

The agent runtime is the core execution engine of OpenSoul, responsible for processing messages, managing sessions, and coordinating tool execution.

Overview

When a message arrives through any channel, the agent runtime:

1. Resolves the route — Maps the message to an agent and session
2. Loads context — Retrieves session history, memory, and configuration
3. Executes the agent — Sends the prompt to the configured model provider
4. Runs tools — Executes any tool calls the model makes
5. Delivers the response — Sends the reply back through the originating channel

Multi-Model Routing

OpenSoul supports routing to multiple model providers:

Provider	Models
OpenAI	GPT-4o, GPT-4, GPT-3.5-turbo, o1, o3, etc.
Anthropic	Claude 4 Opus, Claude 4 Sonnet, Claude 3.5 Sonnet, etc.
Google Gemini	Gemini 2.5 Pro, Gemini 2.0 Flash, etc.
AWS Bedrock	Claude, Titan, etc.
Ollama	Llama, Mistral, and other local models
MiniMax	MiniMax models
OpenRouter	Multi-provider routing

Configure providers via API keys in environment variables or config.

Session Management

Sessions are isolated by sender and workspace:

• Session key: agent:<name>:<channel>:<context>:<sender>
• Transcript loading: Review past conversation history (v0.2.4)
• Session pruning: Automatic cleanup of old sessions
• Compaction: Summarize long conversations to fit context windows

Session Isolation

Each conversation gets its own session context:

• DM sessions — Isolated per sender per channel
• Group sessions — Shared within the group, isolated from DMs
• Workspace sessions — Isolated per agent workspace

Long-Term Memory

OpenSoul includes a vector-search-based memory system:

• Automatic storage — Important information is extracted and stored
• Semantic search — Retrieved by relevance when building context
• Per-agent memory — Each agent maintains its own memory store
• Embedded database — SQLite with sqlite-vec (no external DB required)

Tool Execution

The agent can call tools during execution:

• Built-in tools — File operations, web search, code execution, etc.
• Skill tools — 50+ packaged skills (GitHub, Notion, browser, etc.)
• Sandboxing — Configurable execution boundaries
• Plugin tools — Custom tools via the Plugin SDK

Sandbox Modes

Mode	Behavior
off	Tools run directly on the host
non-main	Group/channel sessions are sandboxed; main sessions run on host
always	All sessions are sandboxed

Multi-Agent Routing

OpenSoul supports multiple agents with independent:

• Workspaces
• Model configurations
• Identity/persona settings
• Tool permissions
• Session contexts

{
  routing: {
    agents: {
      main: {
        workspace: "~/.opensoul/workspace",
        sandbox: { mode: "off" },
      },
      helper: {
        workspace: "~/.opensoul/helper-workspace",
        sandbox: { mode: "always" },
      },
    },
  },
}

Streaming

Agent responses stream in real-time via WebSocket events:

• Partial text as it's generated
• Tool call notifications
• Tool execution results
• Final summary with status

Model Failover

Configure automatic failover between providers:

• Primary and fallback model settings
• Retry logic with configurable delays
• Error-based provider switching

Related Pages

• Architecture — System design overview
• Skills and Tools — Available tools and skills
• Configuration — Agent and session config
• Control UI — Session management in the browser