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.