> ## Documentation Index > Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt > Use this file to discover all available pages before exploring further. # Architecture > Trading Agent file structure, tick engine, and provider system 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: ```yaml theme={null} --- 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: ```markdown theme={null} # 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: 1. **Resolve API client** for the configured server 2. **Run providers** — `executors` and `positions`, filtered by `controller_id` 3. **Read journal context** — learnings, summary, last 3 decisions 4. **Get risk state** — exposure, drawdown, open count. If blocked, skip LLM 5. **Build prompt** — system prompt + strategy + provider summaries + journal 6. **Spawn ACP session** with MCP servers (Hummingbot tools, market data) 7. **Persist** — write snapshot, append tick to journal, update summary ## Risk Engine The Risk Engine (`condor/trading_agent/risk.py`) tracks state and enforces limits: ```python theme={null} 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: ```python theme={null} # 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