Open-Source Agent Architectures — The Harness Handbook Reference

Open-source agent frameworks share common architectural patterns that have proven effective in production. Understanding these patterns gives you a concrete reference for building your own harness.

File-Based Agent Philosophy

Core principle: Agents live in files, not databases.

Rather than storing agent configuration in a database or UI panels, well-designed agent frameworks keep everything version-controllable and human-readable:

~/.agent/workspace/
├── agent-name/
│   ├── AGENTS.md       # Agent instructions & personality
│   ├── VALUES.md       # Agent values & ethical guidelines
│   ├── notes/          # Auto-accumulated knowledge
│   ├── state/          # Auth tokens, session state
│   └── sessions/       # Chat history (transcripts)

This aligns with the CLAUDE.md + MEMORY.md pattern used by Claude Code — the same idea expressed through different file names.

Three-Layer Architecture

Layer 1: Messaging (Channel/Gateway)

Production agent frameworks normalise communication across multiple protocols:

WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, Teams, Matrix, IRC

Key concept: Single control-plane daemon (Gateway) listening on a local port

All clients (desktop app, CLI, web UI, automations) connect via WebSocket
Gateway routes messages to the right agent
Decouples agent from communication protocol

Pattern match in your harness:

If building multi-agent or multi-channel: implement a similar gateway pattern
Route incoming tasks to appropriate agent
Single entrypoint for all communication

Layer 2: Agent Runtime (Brain)

The agentic loop — implements core reasoning:

1. Receive message (from gateway)
2. Load agent context (instructions + notes + relevant session history)
3. Assemble full prompt (instructions + memory + context)
4. Call LLM
5. Parse tool calls from response
6. Dispatch tools (execute against capabilities)
7. Collect results
8. Loop back to step 2 if more tool calls needed
9. Send response back to gateway
10. Persist updated state (new notes, session history)

Matches ReAct pattern: Reason -> Act -> Observe loop

Layer 3: Execution Environment (Body)

Tools that agent can call:

Browser automation (access web, interact with sites)
File operations (read, write, search codebase)
Canvas (rich media, UI components)
Scheduled jobs (recurring tasks)
Sandboxing (prevent unsafe operations)

Multi-Agent Architecture

Production frameworks support multiple isolated agents sharing one Gateway:

Gateway (localhost:18789)
   |-- Agent: researcher
   |   |-- workspace: ~/.agent/workspace/researcher/
   |   +-- role: Search & summarise information
   |-- Agent: coder
   |   |-- workspace: ~/.agent/workspace/coder/
   |   +-- role: Generate and test code
   +-- Agent: reviewer
       |-- workspace: ~/.agent/workspace/reviewer/
       +-- role: Verify work, provide feedback

Routing: Bindings match on:

Channel (Slack, WhatsApp, etc.)
Account (which Slack workspace, which Discord server)
Peer (DM vs group chat)
Optional: Guild/Team (Discord guild, Slack team)

Important: Agent-to-agent messaging is typically OFF by default. Must be explicitly enabled via bindings. Prevents chaos.

Key Patterns for Your Harness

1. Workspace Isolation

Each agent gets isolated workspace:

Separate auth tokens (no cross-contamination)
Separate session history (clean context per agent)
Separate memory (values, notes)
Cannot reuse workspace directory across agents (causes auth/state collisions)

Apply to your harness:

harness-project/
├── agent-1/
│   ├── CLAUDE.md
│   ├── MEMORY.md
│   └── state/
├── agent-2/
│   ├── CLAUDE.md
│   ├── MEMORY.md
│   └── state/

2. Plain-Text Configuration

Agent frameworks use markdown-based configuration (similar to CLAUDE.md):

AGENTS.md example:

# Agent Configuration

## Name
researcher

## Personality
Curious, thorough, detail-oriented. Asks clarifying questions before diving into research.

## Capabilities
- Web search via Bing/Google
- Browser automation (navigate, click, extract)
- File organization (save notes, create summaries)

## Constraints
- Don't spend >5 minutes per query on research
- Summarize findings in max 3 bullet points
- Always cite sources

## Memory Pattern
- Store research findings in ./notes/findings/
- Index in ./notes/index.md
- Weekly consolidation (merge overlapping entries)

Apply to your harness: Use CLAUDE.md or AGENTS.md — both work, pick one convention.

3. Skills System

Production frameworks implement tools as modular “skills”:

Agent
  |-- Skill: Web Search
  |-- Skill: Browser Automation
  |-- Skill: Code Execution
  |-- Skill: File Operations
  +-- Skill: Canvas (rich UI)

Each skill:

Has clear input/output schema
Can be enabled/disabled per agent
Logs all invocations
Has sandboxing rules

Apply to your harness:

class Harness:
  def __init__(self):
    self.skills = {
      "web_search": WebSearchSkill(),
      "code_execution": CodeExecutionSkill(),
      "file_operations": FileOperationsSkill(),
      "browser": BrowserAutomationSkill()
    }
  
  def call_skill(self, name, args):
    return self.skills[name].execute(args)

4. Session Persistence

Production frameworks persist full session history:

~/.agent/workspace/agent-name/sessions/
├── 2026-04-15-09-22-request-001.json
├── 2026-04-15-09-23-response-001.json
├── 2026-04-15-09-24-request-002.json
├── 2026-04-15-09-25-response-002.json
...

Each session step:

Timestamp
User input
Model reasoning
Tool calls
Tool results
Final response

Benefits:

Can replay sessions
Auto-dream can analyse transcripts
Audit trail for debugging
Long-term learning

Apply to your harness:

Save every message pair (user input + model response)
Log every tool call and result
Include timestamps
Use for auto-dream consolidation

5. Values & Ethics (Separate File)

Separating values from instructions is a common pattern:

# Agent Values & Ethics

## Core Values
- Honesty: Always admit uncertainty
- Helpfulness: Go extra mile for users
- Safety: Refuse harmful requests
- Respect: Honor user privacy

## Constraints
- Never generate: personal email addresses, passwords, API keys
- Always: Explain reasoning, cite sources
- When uncertain: Ask clarifying questions

## Decision Framework
When facing tradeoffs between speed and accuracy:
  -> Choose accuracy (speed can always improve, mistakes undermine trust)

When facing tradeoffs between user convenience and privacy:
  -> Choose privacy (fundamental right)

Apply to your harness:

Separate instructions (CLAUDE.md) from values (VALUES.md or ETHICS.md)
Makes constraints explicit and auditable
Helps during auto-dream consolidation

Building Your Own Harness: Using These Patterns

Start: Minimal File-Based Pattern

my-harness/
├── AGENTS.md         # Instructions
├── VALUES.md         # Values & ethics
├── notes/           # Knowledge accumulation
│   ├── index.md
│   └── topics/
├── state/           # Auth, config
└── sessions/        # Session history

Grow: Add Gateway Pattern

When you need multiple agents or multiple channels:

my-harness-platform/
├── gateway.py       # Central entrypoint
├── router.py        # Route to right agent
└── agents/
    ├── researcher/
    │   ├── AGENTS.md
    │   ├── VALUES.md
    │   └── ...
    ├── coder/
    │   ├── AGENTS.md
    │   ├── VALUES.md
    │   └── ...
    └── reviewer/
        ├── AGENTS.md
        ├── VALUES.md
        └── ...

Scale: Add Skill Management

my-harness-platform/
├── skills/
│   ├── web_search.py
│   ├── code_execution.py
│   ├── file_operations.py
│   └── skill_base.py
├── agents/
│   ├── researcher/
│   │   ├── AGENTS.md (lists enabled skills)
│   │   └── skill_config.json
│   └── coder/
│       ├── AGENTS.md
│       └── skill_config.json
└── gateway.py

Comparison: Framework vs Custom Harness

Feature	Existing Framework	Your Harness
Multi-agent	Built-in gateway	Add gateway layer if needed
Multi-channel	WhatsApp, Slack, etc	Only integrate needed channels
Skills/tools	8+ pre-built	Start with 3-5, grow as needed
Persistence	Full session history	Minimal (progress file + git)
Memory pattern	AGENTS.md + notes/	CLAUDE.md + MEMORY.md
Values	Separate values file	In CLAUDE.md or separate
Complexity	Medium (handles lots of cases)	Low -> Medium (as you scale)
Development speed	Fast (framework handles routing)	Fast (less boilerplate)

When to Use a Framework vs Build Custom

Use an existing framework if:

Building conversational agents (WhatsApp, Slack, etc)
Want multi-agent team out-of-the-box
Need to handle multiple channels
Want proven production architecture
Can work with existing skill system

Build custom harness if:

Specific domain (e.g., code generation, data pipeline)
Need tight control over every component
Working with specialised models
Learning/research purposes
Different memory pattern than frameworks assume

Key Takeaway

The best open-source agent frameworks demonstrate that agents live in plain-text files, not databases. Adopting this philosophy in your custom harness gives you:

Version control (git)
Human readability
Auditability
Simplicity (files > databases for this scale)
Collaboration (easier to review, modify)

Use existing frameworks as a reference, but feel free to simplify or specialise for your use case.

Validation Checklist

How do you know you got this right?

Performance Checks

Agent starts and responds to basic command in <5 seconds
Gateway routing latency <100ms between client and agent
Multi-agent setup scales to 5+ agents without performance degradation
Session history persists correctly across restarts

Implementation Checks

AGENTS.md written with name, personality, capabilities, constraints
VALUES.md defined with core values and decision framework
Workspace structure matches pattern (sessions/, notes/, state/)
Skill registry populated with 3+ skills (web_search, file_ops, code_exec minimum)
Session persistence working: .json files created for each message pair
Skill enablement per agent working (different agents have different capabilities)

Integration Checks

Gateway successfully routes to correct agent based on binding rules
Multi-agent isolation verified: agent A can’t access agent B’s workspace
Skill execution returns parseable output for agent to consume
Error recovery: failed skill doesn’t crash agent, error logged and handled
File-based configuration is version-controllable (Git integration works)

Common Failure Modes

Agent workspace collision: Accidentally sharing workspace directory across agents
Skill not found at runtime: Skill registered in config but not implemented
Session history corruption: Concurrent writes to session files from multiple agents
Gateway routing failures: Binding rules too complex or contradictory
Config changes not applied: Configuration cached; restart needed

Sign-Off Criteria

Single agent mode working with 3+ skills
Multi-agent mode tested: 2+ agents working independently
AGENTS.md + VALUES.md written for each agent
Session history persists and is readable
Patterns applied to your harness architecture

File-Based Agent Philosophy

Three-Layer Architecture

Layer 1: Messaging (Channel/Gateway)

Layer 2: Agent Runtime (Brain)

Layer 3: Execution Environment (Body)

Multi-Agent Architecture

Key Patterns for Your Harness

1. Workspace Isolation

2. Plain-Text Configuration

3. Skills System

4. Session Persistence

5. Values & Ethics (Separate File)

Building Your Own Harness: Using These Patterns

Start: Minimal File-Based Pattern

Grow: Add Gateway Pattern

Scale: Add Skill Management

Comparison: Framework vs Custom Harness

When to Use a Framework vs Build Custom

Use an existing framework if:

Build custom harness if:

Key Takeaway

Validation Checklist

Performance Checks

Implementation Checks

Integration Checks

Common Failure Modes

Sign-Off Criteria

See Also