How to Design an AI Trading Bot: Junior to Senior

Junior · 1 of 4

Begin with an LLM conversation

A language model call starts with an array of messages. Append the assistant response and send the expanded array on the next request. That transcript creates the back-and-forth experience.

messages = [
  { role: "user", content: "Explain RSI" },
  { role: "assistant", content: "RSI measures recent momentum..." },
  { role: "user", content: "Now apply that to AAPL" }
]

response = model.generate({ messages })

This version can explain a trading concept. It has no current market data, portfolio state, backtesting engine, scheduler, or brokerage adapter. Controlled context and tools add those capabilities.

Junior · 2 of 4

Assemble the prompt in layers

Do not paste every available fact into one giant prompt. Build the model input from layers with different owners and lifetimes. Stable instructions come first; current goals, state, and retrieved evidence are added for this turn.

Assemble four layers: the versioned system contract, the task procedure, current turn state, and a small relevant evidence slice. Heavy tool results remain in durable storage and re-enter later turns as compact summaries or owner-scoped references.

REACT DECISION CONTRACT
Return JSON with "thought" and exactly one of:
  "actions"     independent product-tool calls
  "command"     agent-control work such as askUser or createSubagents
  "finalAnswer" the completed response

SIMPLIFIED BACKTEST TOOL PROCEDURE
Use "Backtest Portfolios" to launch a native backtest.
Pass the resolved portfolio ID and an explicit date window.
After launch, use the returned backtest ID with "Read Backtest".
Do not launch the same portfolio and window again.

Boundary 1 · The decision model chooses a tool

{
  "thought": "The portfolio exists and the requested window is explicit.",
  "actions": [
    {
      "tool": "Backtest Portfolios",
      "input": "Backtest PORTFOLIO_ID from 2021-01-01 through 2025-12-31."
    }
  ]
}

Boundary 2 · The tool prompt produces its schema

{
  "backtestConfigs": [
    {
      "portfolioId": "PORTFOLIO_ID",
      "startDate": "2021-01-01",
      "endDate": "2025-12-31"
    }
  ]
}

These are two separate model boundaries. The decision model returns an outer JSON decision, but each actions[].input value is plain text. The server appends that text as the user message for the selected tool prompt. The Backtest Portfolios prompt then returns the tool-specific backtestConfigs JSON shown above. Server code resolves the portfolio for the authenticated user, validates the dates and product constraints, launches the native backtest, and returns its backtest ID.

Putting escaped backtestConfigs inside actions[].input would only encode JSON as text for the second model to interpret. It would not provide typed arguments directly to the backtest implementation.

Junior · 3 of 4

Structured output turns a response into an action proposal

Give the decision model a catalog of supported tools. It selects a tool and writes a bounded text instruction for it. The server resolves the selected tool. Some tools handle a complete machine request directly; Backtest Portfolios invokes its own force-JSON prompt to produce the tool-specific schema.

{
  "thought": "I need one current quote and one portfolio read before sizing.",
  "actions": [
    { "tool": "Stock Screener", "input": "Read the current quote for SPY." },
    { "tool": "Read Portfolio", "input": "Read portfolio portfolio_123." }
  ]
}

That JSON is a proposal. The model has not executed a tool, granted itself authority, or written an observation. Host validation is the next step.

Junior · 4 of 4

The host validates the proposal before any tool runs

The host application owns parsing, validation, permissions, execution, and error handling. Reject unknown tools and invalid JSON. Persist a semi-automated proposal instead of running it.

const state = validateAgentState(modelJson)
const actions = getStateActions(state)

if (agent.automationMode === "semi-automated") {
  await persistPendingActionApproval(agent, state)
} else {
  const results = await executeActionBatch(agent, actions)
  await commitObservationsInActionOrder(agent, results)
}

This is the host-side contract, not model freedom. The stepper enforces exactly one decision branch and at most ten actions. Parallel actions are on by default and can be disabled with AGENT_MULTI_ACTIONS_ENABLED=false. Each named tool is resolved by the server before execution. Semi-automated runs persist the exact proposal and wait for approval.

Mid-level · 1 of 5

Route the request before starting an agent

Many users and concurrent turns make a durable agent per message the wrong default. Classify the request first. NexusTrade gives Router V5 the hydrated conversation. The router chooses the smallest supported path and, when durable work is needed, authors the initial plan and title.

type RouterDecision =
  | { action: "Call Tool"; toolName: CatalogPromptName; input: { text?: string } }
  | { action: "Create Agent"; input: { plan: string; title?: string } }
  | { action: "Ask Clarity"; input: { questions: string } }
  | { action: "Continue Agent"; input: {} }

The action set is closed. Catalog names go in toolName, never in action. Ask Clarity questions is one markdown string, not an array. The schema asks for a Create Agent title; the runtime still accepts a plan if the title is missing. Call Tool is one-shot catalog fulfillment. Create Agent and Continue Agent hand the durable loop to ReAct and the stepper. Ask Clarity and Call Tool also return suggested next messages.

Mid-level · 4 of 5

The Router promotes the persisted chat Agent into a run

A NexusTrade conversation already has a persisted Agent document in chat status. Router V5 can answer or ask for clarification while that document remains the conversation container. When it chooses Create Agent, the server upgrades the same _id in place with the plan, title, execution settings, and a runnable status.

{
  "_id": "agent-id",
  "userId": "authenticated-user-id",
  "conversationId": "conversation-id",
  "title": "Portfolio Change Review",
  "initialPrompt": "Review my portfolio and summarize material changes.",
  "plan": "Inspect the portfolio, gather evidence, and summarize material changes.",
  "automationMode": "semi-automated",
  "origin": { "type": "manual" },
  "status": "pending_plan_approval",
  "maxIterations": 40,
  "currentIteration": 0,
  "runIterations": 0
}

These are representative fields after a semi-automated chat is promoted. _id remains the run identity. title and plan come from the Router. initialPrompt keeps the original request. Router and ReAct prompts are snapshotted in AgentPrompts. Chat Aurora uses Router V5. Strategy-triggered LaunchAgent still has a Planner V4 init path. Automated runs enter running instead of waiting for plan approval.

Mid-level · 5 of 5

Keep prior tool payloads out of the next decision

The current request determines which product data belongs in the next model call. This portfolio-creation request only needs its new specification, current plan, entitlements, and available tools. Full results from earlier research add no decision input.

Mid-level · prompt operations

Version the prompt configuration and track schema compatibility

Once more than one person edits prompts, a save is not enough. Shared prompts need versioning. Promotion quality is a separate question from save.

A prompt is executable application configuration. Changing its system instructions, examples, model, JSON setting, or referenced schema can change agent behavior. NexusGenAI is the registry. A save snapshots the configuration and increments currentVersion. Restore is a version read, not a bakeoff. The referenced schema is a separate dependency, so compatibility belongs to the prompt version that uses it.

{
  "name": "Agent decision prompt",
  "currentVersion": 42,
  "model": "selected-model",
  "forceJSON": true,
  "schemaId": "agent-decision-schema-id",
  "prompt": "Return exactly one ReAct decision branch...",
  "examples": ["..."]
}

Calibrate a judge on reviewed good and broken examples before using its score. Compare versions on the same held-out cases, then change the component that owns the failure. Permission errors belong to product checks; stale evidence belongs to retrieval. Runtime code can restore a prior NexusGenAI version without changing the stepper.

Senior · 1 of 2

Persist the workflow, then let workers claim one step

Agent {
  title, initialPrompt, lastUserRequest, plan, conversationId
  status, previousStatus, automationMode
  currentIteration, totalIterations, runIterations, maxIterations
  currentState: {
    thought, actionBatchId,
    actions[] | command | finalAnswer,
    commandExecution,
    pendingComputations[]
  }
  parentAgentId, childAgentIds[], subagentType
  claimedBy, claimedAt, claimToken, claimGeneration
  claimHeartbeatAt, claimExpiresAt, stateVersion
  origin, portfolioContext, costCeilingUsd, treeCostUsd
  updatedAt, lastProgressAt, completedAt, stoppedAt, error
}

Aurora stores the run as a durable agent document. A worker atomically claims a runnable agent, performs a bounded step, renews ownership while active, and releases the claim when the agent finishes or waits. Another worker can recover an abandoned run from the last committed observation.

Practical implementation paths

Choose the shell; keep authority in the product

Claude Code, Cursor, and Codex demonstrate the shell: instructions, tools, context, and approvals. Aurora is the NexusTrade implementation: portfolio context, durable research, staged orders, and financial authority outside the model. Any shell still depends on server-side validation.