Architecture

Each Trading Agent is a folder-based entity with structured files that define its behavior, track state, and accumulate learnings.

System Architecture

                ┌──────────────────────────── Trading Agent ───────────────────────────┐
                │                                                                       │
                │   Strategy (agent.md)        Journal (per session)     Learnings.md   │
                │   ───────────────────        ────────────────────       ────────────  │
                │   - system prompt            - summary                  cross-session │
                │   - default config           - decisions                lessons       │
                │   - skills/routines          - tick-by-tick log                       │
                │                              - snapshot_N.md                          │
                │                                                                       │
                │                            ┌──── TickEngine ────┐                     │
                │                            │  every N seconds:  │                     │
                │   Routines  ───────────►   │  1. run providers  │  ────► MCP Tools    │
                │  (deterministic            │  2. read journal   │       - candles     │
                │   data prep)               │  3. build prompt   │       - orderbook   │
                │                            │  4. ACP session    │       - executors   │
                │                            │  5. capture tools  │       - notify      │
                │                            │  6. write snapshot │                     │
                │                            └────────────────────┘                     │
                │                                                                       │
                └───────────────────────────────────────────────────────────────────────┘
                                                      │
                                                      ▼
                                         Hummingbot Executors
                                 (filtered by controller_id == agent_id)

Directory Structure

Each Condor Trading Agent (CTA) is a directory containing structured files:

trading_agents/
  my_strategy/
    agent.md                  # Strategy definition (frontmatter + LLM instructions)
    config.yml                # Runtime configuration (editable)
    learnings.md              # Cross-session insights (max 20)
    routines/                 # Deterministic Python helpers
    trading_sessions/
      session_N/
        journal.md            # Summary, decisions, ticks, executors
        snapshots/
          snapshot_1.md       # Full prompt + response for tick 1
          snapshot_2.md
    dry_runs/
      experiment_1.md         # One-shot dry-run results

Two Memory Files

File	Scope	Purpose
`journal.md`	Per-session	Short-term memory for the current trading session
`learnings.md`	Cross-session	Long-term memory that persists across all sessions

Journal: What the agent did in this session—tick log, decisions, executor states. Learnings: Lessons that apply to all sessions—common errors, configuration tips, market insights.

agent.md

The strategy definition uses YAML frontmatter for configuration and Markdown for instructions:

---
name: Grid Market Maker
tick_interval: 60
connectors:
  - binance_perpetual
  - jupiter

configs:
  trading_pair: SOL-USDC
  grid_levels: 5
  spread_percentage: 0.3

limits:
  max_position_size_quote: 500
  max_single_order_quote: 100
  max_daily_loss_quote: 50
  max_open_executors: 10
  max_drawdown_pct: 10
---

## Goal
Provide liquidity around the mid-price while managing inventory risk.

## Strategy Rules
1. Maintain symmetric grid unless inventory exceeds threshold
2. Widen spreads during high volatility (ATR > 2%)
3. Pause trading if funding rate exceeds 0.1% against position

Configs vs Limits

Configs

Agent-suggestible parameters that control trading behavior:

The agent can suggest changes based on learnings
User must approve before changes take effect
Examples: trading_pair, spread_percentage, tick_interval, grid_levels

Limits

User-only guardrails enforced by the Risk Engine:

Safety boundaries the agent cannot exceed
Only modifiable by the user, never by the agent
Examples: max_position_size_quote, max_daily_loss_quote, max_drawdown_pct

learnings.md

Persists across sessions, accumulating insights:

# Learnings

## Active Insights
- [2026-03-27 14:30] Wider spreads (0.5% vs 0.3%) reduced adverse selection during Asian session
- [2026-03-26 09:15] Grid rebalancing at 5% threshold outperforms 10% for SOL-USDC
- [2026-03-25 16:45] Funding rate spikes above 0.05% correlate with 2-hour reversals

Maximum 20 entries to prevent context bloat. New insights replace older ones.

Tick Loop

Each tick (TickEngine._tick) executes:

Resolve API client for the configured server
Run providers — executors and positions, filtered by controller_id
Read journal context — learnings, summary, last 3 decisions
Get risk state — exposure, drawdown, open count. If blocked, skip LLM
Build prompt — system prompt + strategy + provider summaries + journal
Spawn ACP session with MCP servers (Hummingbot tools, market data)
Persist — write snapshot, append tick to journal, update summary

Risk Engine

The Risk Engine (condor/trading_agent/risk.py) tracks state and enforces limits:

class RiskState:
    daily_pnl: float          # Today's realized P&L
    total_exposure: float     # Current open position value
    executor_count: int       # Number of active executors
    drawdown_pct: float       # Current drawdown percentage
    daily_cost: float         # LLM costs today
    is_blocked: bool          # Kill switch status
    block_reason: str         # Why blocked (if applicable)

Pre-tick Validation

Blocks the entire tick if:

daily_pnl < -max_daily_loss_quote
drawdown_pct > max_drawdown_pct
daily_cost > max_cost_per_day_usd

Per-executor Validation

Blocks executor creation if:

executor_count >= max_open_executors
order_amount > max_single_order_quote
total_exposure + new_amount > max_position_size_quote

Providers

Providers fetch deterministic data before each tick:

Provider	Output
`executors`	Active executors filtered by `controller_id`, with status and P&L
`positions`	Held positions from closed executors, with breakeven and unrealized P&L

Provider output has two parts:

data: Structured data for internal tracking
summary: Human-readable string included in the LLM prompt

Routines

Custom Python helpers in the routines/ directory:

# routines/process_candles.py
async def compute_vwap(candles):
    """Compute VWAP from candle data."""
    total_volume = sum(c.volume for c in candles)
    return sum(c.close * c.volume for c in candles) / total_volume

Routines are deterministic—same input always produces same output.

Inspecting Activity

Location	Content
`sessions/session_N/journal.md`	Chronological summary, decisions, tick log
`sessions/session_N/snapshots/snapshot_K.md`	Full tick: prompt, response, tool calls
`learnings.md`	Lessons the agent chose to keep
`dry_runs/experiment_N.md`	Dry-run results

Injecting Information

You can manually add to learnings.md—the agent doesn’t know whether it wrote the entry or you did. Useful for:

Pre-seeding knowledge before deployment
Adding market context the agent can’t observe
Correcting agent behavior

Via web dashboard: Trading Agents → Select agent → Learnings → Edit Via file: Edit trading_agents/my_strategy/learnings.md directly

Condor

Getting Started

Trading Agents

Executors

Routines

Bots

Other Condor Features

System Architecture

Directory Structure

Two Memory Files

agent.md

Configs vs Limits

Configs

Limits

learnings.md

Tick Loop

Risk Engine

Pre-tick Validation

Per-executor Validation

Providers

Routines

Inspecting Activity

Injecting Information

​System Architecture

​Directory Structure

​Two Memory Files

​agent.md

​Configs vs Limits

​Configs

​Limits

​learnings.md

​Tick Loop

​Risk Engine

​Pre-tick Validation

​Per-executor Validation

​Providers

​Routines

​Inspecting Activity

​Injecting Information

System Architecture

Directory Structure

Two Memory Files

agent.md

Configs vs Limits

Configs

Limits

learnings.md

Tick Loop

Risk Engine

Pre-tick Validation

Per-executor Validation

Providers

Routines

Inspecting Activity

Injecting Information