Agent Creation

Agents are the core unit of YorN. Each agent encapsulates a trading strategy, risk parameters, and execution logic. This guide covers everything from creating agents with natural language to writing custom Strategy classes.

What is an Agent

A YorN agent is an autonomous program that monitors prediction markets, evaluates trading opportunities, and executes trades based on a defined strategy. Every agent consists of three components:

  • Strategy -- The decision-making logic that generates buy/sell signals
  • Risk Manager -- Constraints on position size, daily loss limits, and exposure
  • Executor -- The engine that submits orders to Kalshi (paper or live)

Agents run continuously, processing market data in real time via WebSocket feeds. When the strategy generates a signal with sufficient confidence, the executor places the trade after the risk manager approves it.

Prompt

Describe thesis

Generate

AI writes code

Validate

AST safety check

Deploy

Start trading

Learn

Self-improve

Creating via Natural Language

The simplest way to create an agent is to describe your trading thesis in plain English. The AI agent builder uses Claude to parse your intent, identify market categories, define entry/exit conditions, and generate a complete Strategy class.

Writing Effective Prompts

A good prompt specifies four things: what market to trade, when to enter, when to exit, and how much to risk. Here are examples ranked from basic to advanced:

Basic Prompt
"Buy YES on NBA home teams when they are favored." // Generated strategy will: // - Monitor NBA game markets // - Check home team spread // - Buy YES when home team is favored // - Use default position sizing (1% of balance)
Advanced Prompt
"Trade FOMC rate decision markets. Buy YES on 'hold' when CME FedWatch shows >75% hold probability and the Kalshi YES price is below 70c. Scale into positions: 25% at 65c, 50% at 60c, 100% at 55c. Max exposure $200. Stop loss at 40c. Take profit at 90c or 24h before event close." // Generated strategy includes: // - Multi-condition entry logic // - Scaled position sizing // - Hard stop loss and take profit // - Time-based exit before event resolution

The more specific your prompt, the better the generated strategy. Include price thresholds, position sizing rules, and exit conditions for the best results.

The Strategy Class

Every agent is powered by a Strategy class. Whether created by AI or written manually, all strategies follow the same structure. The Strategy base class provides lifecycle hooks that you override with your logic.

strategy.py Strategy Class Skeleton
class MyStrategy(Strategy): def __init__(self, config): super().__init__(config) self.name = "MyStrategy" self.markets = ["NBA", "NFL"] self.min_confidence = 0.65 async def evaluate(self, market_data): # Core decision logic # Receives real-time market data dict # Returns a Signal or None price = market_data["yes_price"] volume = market_data["volume_24h"] if price < 0.45 and volume > 10000: return Signal( action="buy", side="yes", confidence=0.8, reason="Underpriced with high volume" ) return None def position_size(self, signal, balance): # How many contracts to buy base = balance * 0.02 # 2% of balance return int(base * signal.confidence) def risk_check(self, signal, portfolio): # Validate against risk rules if portfolio.daily_loss > portfolio.max_loss: return False if portfolio.open_positions >= 5: return False return True

Signal Object

The Signal object is the return type of the evaluate method. It tells the executor what to do:

Signal Fields
Signal( action="buy", # "buy" | "sell" | "hold" side="yes", # "yes" | "no" confidence=0.82, # 0.0 to 1.0 reason="...", # Human-readable explanation limit_price=0.55, # Optional limit price ttl=300, # Signal expiry in seconds )

Market Data Object

The market_data dictionary passed to evaluate contains:

market_data Fields
{ "ticker": "KXNBA-LAL-BOS-2026-02-18", "title": "Will the Lakers beat the Celtics?", "category": "sports", "yes_price": 0.42, "no_price": 0.58, "volume_24h": 15420, "open_interest": 8200, "close_time": "2026-02-19T03:00:00Z", "price_history": [0.45, 0.44, 0.43, 0.42], "spread": 0.02 }

AST Safety Validation

Every generated or uploaded strategy undergoes Abstract Syntax Tree (AST) validation before deployment. This ensures that agent code cannot perform dangerous operations.

Blocked Operations

  • import statements -- No external library imports allowed
  • File I/O -- No open(), read(), write() calls
  • Network access -- No requests, urllib, socket usage
  • System calls -- No os.system(), subprocess, eval(), exec()
  • Global state mutation -- No modifying module-level variables

Allowed Operations

  • Arithmetic and comparison operators
  • Built-in math functions: min, max, abs, round, sum
  • List, dict, and string operations
  • Control flow: if, for, while, try/except
  • Instance variable access on self

If AST validation fails, the agent will not be created. The error response includes the specific violation so you can adjust your prompt or code.

Deploying Agents

Once an agent passes validation, it can be deployed in paper or live mode. Deployment creates a persistent process that monitors markets and executes the strategy.

Configuration Options

Agent Configuration JSON
{ "name": "FOMC-Rate-Hold", "mode": "paper", // "paper" | "live" "market_category": "economics", "max_position": 100, // Max contracts per trade "daily_loss_limit": 50.00, // Max daily loss in dollars "risk_limit": 0.05, // Max % of balance per trade "cooldown": 300, // Seconds between trades "auto_restart": true, // Restart on crash "schedule": { "start": "09:00", "end": "22:00", "timezone": "US/Eastern" } }

Managing Agents

The dashboard provides full control over your deployed agents. You can pause, resume, stop, or reconfigure agents at any time.

Running

Agent is actively monitoring markets and executing trades.

Paused

Agent is paused. Existing positions remain open but no new trades are placed.

Stopped

Agent is fully stopped. All positions are closed or marked for manual review.

Agent API Endpoints

Agent Management
GET /api/agents # List all agents POST /api/agents # Create new agent GET /api/agents/{id} # Get agent details PUT /api/agents/{id} # Update configuration POST /api/agents/{id}/start # Start agent POST /api/agents/{id}/pause # Pause agent POST /api/agents/{id}/stop # Stop agent DELETE /api/agents/{id} # Delete agent

Next Steps