ai/doc/agent_harness.md

Agent Harness Architecture

The Agent Harness is the core orchestration layer for the Dexorder AI platform, built on LangChain.js and LangGraph.js.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Gateway (Fastify)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  WebSocket   │  │  Telegram    │  │  Event       │     │
│  │  Handler     │  │  Handler     │  │  Router      │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                  │                  │              │
│         └──────────────────┴──────────────────┘              │
│                            │                                 │
│                    ┌───────▼────────┐                        │
│                    │ Agent Harness  │                        │
│                    │  (Stateless)   │                        │
│                    └───────┬────────┘                        │
│                            │                                 │
│         ┌──────────────────┼──────────────────┐             │
│         │                  │                  │             │
│    ┌────▼─────┐      ┌────▼─────┐      ┌────▼─────┐       │
│    │   MCP    │      │   LLM    │      │
│    │ Connector│      │  Router  │      │
│    └────┬─────┘      └────┬─────┘      │
│         │                  │             │
└─────────┼──────────────────┼─────────────┘
          │                  │
          ▼                  ▼
   ┌────────────┐     ┌───────────┐
   │   User's   │     │    LLM    │
   │    MCP     │     │ Providers │
   │ Container  │     │(Anthropic,│
   │ (k8s pod)  │     │  OpenAI,  │
   │            │     │   etc)    │
   └────────────┘     └───────────┘

Message Processing Flow

When a user sends a message:

1. Gateway receives message via channel (WebSocket/Telegram)
   ↓
2. Authenticator validates user and gets license info
   ↓
3. Container Manager ensures user's MCP container is running
   ↓
4. Agent Harness processes message:
   │
   ├─→ a. MCPClientConnector fetches context resources:
   │      - context://user-profile
   │      - context://conversation-summary
   │      - context://workspace-state
   │      - context://system-prompt
   │
   ├─→ b. Build system prompt:
   │      - Base platform prompt
   │      - User profile context
   │      - Workspace state
   │      - Custom user instructions
   │
   ├─→ d. ModelRouter selects LLM:
   │      - Based on license tier
   │      - Query complexity
   │      - Configured routing strategy
   │
   ├─→ e. LLM invocation with tool support:
   │      - Send messages to LLM
   │      - If tool calls requested:
   │         • Platform tools → handled by gateway
   │         • User tools → proxied to MCP container
   │      - Loop until no more tool calls
   │
   ├─→ f. Save conversation to MCP:
   │      - mcp.callTool('save_message', user_message)
   │      - mcp.callTool('save_message', assistant_message)
   │
   └─→ g. Return response to user via channel

Core Components

1. Agent Harness (gateway/src/harness/agent-harness.ts)

Stateless orchestrator - all state lives in user's MCP container.

Responsibilities:

• Fetch context from user's MCP resources
• Build prompts with full context
• Route to appropriate LLM
• Handle tool calls (platform vs user)
• Save conversation back to MCP
• Stream responses to user

Key Methods:

• handleMessage(): Process single message (non-streaming)
• streamMessage(): Process with streaming response
• initialize(): Connect to user's MCP server

2. MCP Client Connector (gateway/src/harness/mcp-client.ts)

Connects to user's MCP container using Model Context Protocol.

Features:

• Resource reading (context://, indicators://, strategies://)
• Tool execution (save_message, run_backtest, etc.)
• Automatic reconnection on container restarts
• Error handling and fallbacks

3. Model Router (gateway/src/llm/router.ts)

Routes queries to appropriate LLM based on:

• License tier: Free users → smaller models, paid → better models
• Complexity: Simple queries → fast models, complex → powerful models
• Cost optimization: Balance performance vs cost

Routing Strategies:

• COST: Minimize cost
• COMPLEXITY: Match model to query complexity
• SPEED: Prioritize fast responses
• QUALITY: Best available model

4. Memory Layer

Three-Tier Storage:

Redis (Hot Storage)

• Active session state
• Recent conversation history (last 50 messages)
• LangGraph checkpoints (1 hour TTL)
• Fast reads for active conversations

Iceberg (Cold Storage)

• Full conversation history (partitioned by user_id, session_id)
• Checkpoint snapshots for replay
• Analytics and time-travel queries
• GDPR-compliant with compaction

5. Skills vs Subagents

Skills (gateway/src/harness/skills/)

Use for: Well-defined, specific tasks

• Market analysis
• Strategy validation
• Single-purpose capabilities
• Defined in markdown + TypeScript

Structure:

class MarketAnalysisSkill extends BaseSkill {
  async execute(context, parameters) {
    // Implementation
  }
}

Subagents (gateway/src/harness/subagents/)

Use for: Complex domain expertise with context

• Code reviewer with review guidelines
• Risk analyzer with risk models
• Multi-file knowledge base in memory/ directory
• Custom system prompts

Structure:

subagents/
  code-reviewer/
    config.yaml              # Model, memory files, capabilities
    system-prompt.md         # Specialized instructions
    memory/
      review-guidelines.md
      common-patterns.md
      best-practices.md
    index.ts

Recommendation: Prefer skills for most tasks. Use subagents when you need:

• Substantial domain-specific knowledge
• Multi-file context management
• Specialized system prompts

6. Workflows (gateway/src/harness/workflows/)

LangGraph state machines for multi-step orchestration:

Features:

• Validation loops (retry with fixes)
• Human-in-the-loop (approval gates)
• Error recovery
• State persistence via checkpoints

Example Workflows:

• Strategy validation: review → backtest → risk → approval
• Trading request: analysis → risk → approval → execute

User Context Structure

Every interaction includes rich context:

interface UserContext {
  userId: string;
  sessionId: string;
  license: UserLicense;

  // Multi-channel support
  activeChannel: {
    type: 'websocket' | 'telegram' | 'slack' | 'discord';
    channelUserId: string;
    capabilities: {
      supportsMarkdown: boolean;
      supportsImages: boolean;
      supportsButtons: boolean;
      maxMessageLength: number;
    };
  };

  // Retrieved from MCP + RAG
  conversationHistory: BaseMessage[];
  relevantMemories: MemoryChunk[];
  workspaceState: WorkspaceContext;
}

User-Specific Files and Tools

User's MCP container provides access to:

Indicators (indicators/*.py)

• Custom technical indicators
• Pure functions: DataFrame → Series/DataFrame
• Version controlled in user's git repo

Strategies (strategies/*.py)

• Trading strategies with entry/exit rules
• Position sizing and risk management
• Backtestable and deployable

Watchlists

• Saved ticker lists
• Market monitoring

Preferences

• Trading style and risk tolerance
• Chart settings and colors
• Notification preferences

Executors (sub-strategies)

• Tactical order generators (TWAP, iceberg, etc.)
• Smart order routing

Container Lifecycle

User Container Creation

When user connects:

1. Gateway checks if container exists (ContainerManager)
2. If not, creates Kubernetes pod with:
   • Agent container (Python + conda)
   • Lifecycle sidecar (container management)
   • Persistent volume (git repo)
3. Waits for MCP server ready (~5-10s cold start)
4. Establishes MCP connection
5. Begins message processing

Container Shutdown

Free users: 15 minutes idle timeout Paid users: Longer timeout based on license On shutdown:

• Graceful save of all state
• Persistent storage retained
• Fast restart on next connection

MCP Authentication Modes

1. Public Mode (Free tier): No auth, read-only, anonymous session
2. Gateway Auth (Standard): Gateway authenticates, container trusts gateway
3. Direct Auth (Enterprise): User authenticates directly with container

Implementation Status

✅ Completed

• Agent Harness with MCP integration
• Model routing with license tiers
• Document loader for global knowledge
• EmbeddingService (Ollama/OpenAI)
• Skills and subagents framework
• Multi-channel support (WebSocket, Telegram)
• Container lifecycle management
• Event system with ZeroMQ

🚧 In Progress

• Iceberg integration (checkpoint-saver, conversation-store)
• More subagents (risk-analyzer, market-analyst)
• LangGraph workflows with interrupts
• Platform tools (market data, charting)

📋 Planned

• File watcher for hot-reload in development
• Advanced RAG strategies (hybrid search, re-ranking)
• Caching layer for expensive operations
• Performance monitoring and metrics

References

• Implementation: gateway/src/harness/
• Documentation: gateway/src/harness/README.md
• Knowledge base: gateway/knowledge/
• LangGraph: https://langchain-ai.github.io/langgraphjs/
• MCP Spec: https://modelcontextprotocol.io/