Agent basics tier · Reference card · Agents Academy

Agent basics.
One sheet.

Tool-use contract, the canonical agent loop, three memory layers, persistence patterns, and the safety perimeter every trading agent assumes from day one. Pin it; print it; come back to it.

Back to Module 06

Tool contract

M04

Every tool the model can invoke needs three fields:

{ name: "browse_markets", description: "List active Limitless markets matching a tag and a min volume.", input_schema: { type: "object", properties: { tag: { type: "string" }, minVol: { type: "number" } }, required: ["tag"] } }

The description is the most important field. It’s how you teach the model when this tool is the right answer.

The agent loop

M05

while True: r = llm.invoke(messages, tools) if r.kind == "assistant": return r # done out = run_tool(r.tool_call) messages.extend([r, out]) if step++ > CAP: # guard return TimedOut

Termination. Plain assistant message, step cap, or kill-switch flag from the dashboard.

Three memory layers

M06

Short-term	context window
Session	NDJSON trace
Long-term	SQLite / JSON

Don’t cross streams. Long-term state goes through tool calls, not prompt-stuffing. Session traces don’t replace state; state doesn’t replace traces.

Atomic write

M06

// Always: temp + rename fs.writeFile(path + ".tmp", j); fs.rename(path + ".tmp", path); // Concurrent? add a lock. flock(path, EX, () => { // write here });

Atomic rename survives crashes. Add flock when more than one process can write.

Trace event shape

M06

{ runId, step, timestamp, kind, // see below payload // pre-redacted }

Kinds: prompt, assistant, tool_call, tool_result, error. One line per event. Filename: YYYY-MM-DD.ndjson.

Do I need a vector store?

M06

Open positions, P&L, risk budgets. → SQLite.
Last 30 days of fills. → NDJSON + tail.
Daily P&L summary. → CSV.
Thousands of human research notes. → vector store.
“Find similar past markets to this new one.” → vector store.
Anything else. → you don’t need it yet.

Safety perimeter

M03

Three boundaries every trading agent assumes from day one:

Boundary	Mechanism	If breached
Key custody	Wallet sign as a separate process / hardware	Compromised agent ≠ drained wallet
Risk caps	Max position size + daily loss enforced in `place_limit_order` tool, not the prompt	Hallucinated “just one more” can’t exceed cap
Kill switch	Flag file (`$ACADEMY_DATA_DIR/kill_switch.flag`) checked at top of every loop iteration	You stop the agent in 1 cycle, panel tap or one command

Mental model. The LLM is a tenant in a sandbox you built. The walls are tools. The roof is risk caps. The door is the kill switch. None of those should depend on the model behaving well.

Pitfalls that bite production agents

Cross-module

Stuffing state into the prompt. Context is short-term, not long-term. Use tool calls.
Atomic write, two writers. Atomic rename + flock when more than one process can hold the file.
Trace logs leak secrets. Pre-redact env vars, headers, anything >200 chars in tool_call.input. Rotate any key that appears.
No step-count cap on the loop. An LLM that loops forever costs money and emits one bad order per iteration.
Tools without idempotency. Retried tool calls must produce the same effect, place_limit_order needs a client nonce.
Reading positions immediately after a fill. Indexers lag. Trust the order ack; reconcile on a separate cadence.