Agent Built-In Tools

LumiBot agents are useful because they can inspect the same strategy state that your Python code can inspect. Built-in tools are added automatically when an agent is created, so a strategy author does not need to manually wire common market, account, research, memory, or notification tools.

The important design rule is simple:

  • Research agents can inspect evidence.

  • Trading agents can inspect evidence and mutate orders.

  • Backtests expose only data available at the simulated strategy datetime.

Trading Permissions

Use allow_trading=False for any agent that should research, summarize, or review without changing broker state.

self.agents.create(
    name="researcher",
    model="openai/gpt-6-luna",
    allow_trading=False,
    system_prompt="Gather market data, indicators, news, filings, fundamentals, and macro context.",
)

With allow_trading=False, LumiBot removes tools that mutate orders and the actual-decision memory write:

  • submit order

  • submit multi-leg order

  • modify order

  • cancel order

  • remember decision

Read-only tools remain available. A research agent can still inspect cash, positions, open orders, historical prices, indicators, news, SEC filings, FRED macro data, memory, and notifications.

Lumibot agent tool permissions

Use allow_trading=True only for the final agent that is allowed to place or change orders. In an AI trading team workflow, that is usually the portfolio manager or trader agent.

Network Permissions

The outbound network tools (http_request, rss_fetch, and every browser_* tool) are off by default. Fetched pages are untrusted input, and a network tool is the channel a prompt-injected page could use to send agent context somewhere else. Keeping them out of the default set also keeps trading agents focused on account and market tools.

Opt an agent in with allow_network=True:

self.agents.create(
    name="page_researcher",
    model="openai/gpt-6-luna",
    allow_trading=False,
    allow_network=True,
    system_prompt="Use http_request to read the supplied public page. Do not submit orders.",
)

Listing a network tool explicitly, for example tools=[BuiltinTools.web.http_request()], is also an opt-in, but only for the tools you list. allow_network=False removes network tools even when they are listed. Give network access to the research agent that fetches pages, not to the trading agent.

Order Readiness

Agent order tools are intentionally broker-like: LumiBot either submits the exact order requested or rejects it. It does not silently resize, clip, or normalize a requested order into a different order.

Before orders_submit_order or orders_submit_multileg can submit an order, the agent must inspect the required account, open-order, and price context in the same agent run:

  • account_portfolio for cash and portfolio value

  • complete unfiltered account_positions pagination for current holdings

  • complete unfiltered orders_open_orders pagination for active orders

  • market_last_price for the ordered symbol, or market_last_prices including that symbol

If those checks are missing, the order tool returns an ORDER_READINESS_REQUIRED error to the agent instead of submitting the order. This is not a universal margin model. LumiBot does not try to enforce one broker/country/asset-class leverage rule across stocks, ETFs, options, futures, forex, and crypto. The readiness gate only prevents blind trading; sizing judgment remains with the strategy and agent. A fresh injected account snapshot satisfies the initial account and open-order checks only when all of its completeness flags are true. After an order mutation, the agent must refresh the account and open-order context before submitting another order.

Option orders ask for more. The agent prompt and the built-in options-trading skill tell the agent to call account_portfolio, account_positions, and orders_open_orders in the run before any option order, even when the injected snapshot is complete, because an option package depends on exact signed contract positions and pending packages. The skill also tells the agent to apply only the expiration, delta, and width limits the user or active rules state, and to measure deltas with the Greek tools instead of declining from strike distance alone.

Opening an option position (buy_to_open, sell_to_open, or a plain buy or sell that does not reduce a held contract) also requires a successful options_get_chain for the underlying in the same run. Without it the order tool returns ORDER_READINESS_REQUIRED. Expiration and delta helpers only return candidates; the chain shows what is listed. Closing a held contract does not need the chain.

Market-price tools:

  • market_last_price accepts one tradable symbol per call.

  • market_last_prices accepts a JSON-friendly symbol list (symbols or symbols_json, cap 150) and returns last prices at the current runtime datetime plus available/missing symbol lists. Prefer this when scanning a provided universe.

  • market_load_history_table still loads one symbol per call; load finalists after the batch scan.

Market And Account State

These tools let agents understand what the strategy already knows:

  • current datetime

  • cash and portfolio value

  • positions

  • open orders

  • historical bars and market data

  • account and broker context available to the strategy

These tools are read-only. They remain available even when allow_trading=False.

Options And Multi-Leg Orders

LumiBot exposes generic options capabilities to every agent:

  • options_get_chain

  • options_get_strikes

  • options_get_greeks

  • options_find_strike_for_delta

  • options_find_expiration

  • options_evaluate_market

  • options_calculate_multileg_price

  • options_check_spread_profit

The tools retrieve data through the configured LumiBot broker or backtest data source. They do not select a named options strategy or choose its legs. The agent must select an available expiration, exact listed strikes, quantities, and actions from the returned evidence.

options_find_expiration finds a listed expiration on or after a target date using min_days and/or target_date. options_check_spread_profit estimates multi-leg P&L percentage from exact legs and the opening cash cost.

orders_submit_multileg submits two or more exact option legs as one atomic multi-leg order. Opening actions are buy_to_open and sell_to_open. Closing actions are buy_to_close and sell_to_close. Signed net prices are positive for debits and negative for credits.

If the active broker does not support atomic package submission, LumiBot rejects the request before submitting any child leg. A multi-leg request never falls back to independent orders.

After submission, agents can call orders_get_status or orders_wait_for_terminal to verify identifiers. Never treat a submitted status as a fill unless is_filled is true.

account_positions and orders_open_orders return compact, deterministic pages with 50 records by default and at most 100 per call. Every response includes total, matched, returned, omitted, complete, and next-offset metadata. When complete is false, omitted records still exist; continue through the remaining unfiltered pages before treating the account view as complete. Every page also carries a content-derived snapshot_id. Full-account readiness accepts a page sequence only when every page has the same identifier; if positions or open orders change between calls, restart pagination at offset zero.

Both tools support exact symbol, asset type, expiration, strike, and option right filters. This allows an agent to find a specific contract even when it falls outside the first visible page. Open-order filters also inspect compact multi-leg child contracts. A targeted lookup proves whether that contract is present, while complete unfiltered pagination is still required for full order-readiness.

Position entries include the exact compact asset identity, signed quantity, closing side and quantity for options, and available average fill, current price, market value, and P&L fields. Missing optional values are omitted rather than represented as zero. The injected runtime snapshot uses the same compact position and order representation as the tools, so inspecting the account does not unexpectedly expand raw broker or internal Python objects into model context.

Technical Indicators

Indicator tools expose LumiBot’s indicator system to agents:

  • list_indicators

  • get_indicator

  • get_indicators

Indicator input is restricted to rows at or before strategy time, not just the returned value. Noncausal parameters are rejected. Completion of a timestamped bar follows the selected data source’s contract; see Indicators.

Use get_indicators with requests_json for independent parameters and timeframes. Each of up to 50 requests needs a unique id and indicator; optional parameters is an object and timestep overrides the batch default:

get_indicators(symbol="SPY", requests_json='[
  {"id":"sma50","indicator":"sma","parameters":{"length":50}},
  {"id":"sma200","indicator":"sma","parameters":{"length":200}},
  {"id":"minute_rsi","indicator":"rsi","timestep":"minute","parameters":{"length":14}}
]')

Results retain their request IDs. A failed calculation does not hide other results; complete=false means at least one request failed. The original indicators=["rsi", "macd"] interface remains supported for default parameters. Do not combine indicators and requests_json in one call. Request ids, indicator names and timesteps must be nonempty strings of at most 128 characters. Malformed envelopes fail before data retrieval.

Testing and eval costs

The source release eval runner uses a durable, per-model-call spending ledger. Actor calls, judge calls and continuations reserve their maximum cost before inference. Missing usage after a failure retains its reservation across resumes; it is not counted as a free call. This opt-in release-test policy does not alter ordinary strategy execution or impose a new provider account limit.

Freshness remains 90 days for compatible evidence. Runtime, indicator, broker and installed SDK changes invalidate the relevant shared fingerprint. See the repository’s docs/AGENT_EVALS.md for the ledger and resume contract.

SEC Fundamentals And Filings

SEC tools use public SEC EDGAR data directly and cache responses locally. They do not require an API key.

Common tools include:

  • get_income_statement

  • get_balance_sheet

  • get_cash_flow

  • get_company_facts

  • get_filings

  • search_filing

  • get_filing_document

get_filings for a symbol the SEC ticker map does not list (ETFs, foreign listings, crypto, private names) returns an empty filings list with available: false and reason: "no_sec_cik" instead of an error. The absence is reported, never filled in.

Backtests gate filings by filed date or acceptance timestamp, so an agent cannot read a filing before it existed. Use search_filing before get_filing_document when the filing is large and the agent only needs a specific section.

HTTP And RSS

These tools require the network opt-in described in Network Permissions.

http_request is the general outbound web/API tool. It supports GET, HEAD, OPTIONS, POST, PUT, PATCH, and DELETE with query parameters, JSON, form, raw, and multipart bodies. Responses are structured and size-bounded; binary bodies are base64 encoded. A strategy-level client retains cookies across calls and validates the destination again after every redirect.

Authentication is supplied through named, host-scoped credential profiles rather than placed in agent prompts. Profiles support bearer, basic, API-key, custom-header, cookie, and client-certificate authentication. Secrets are injected only for matching hosts and are not returned in tool output. The default network policy blocks loopback, private, link-local, reserved, and cloud-metadata destinations; a trusted internal host must be explicitly allowlisted by the application that creates the client. This guard preserves the full HTTP method set while preventing an untrusted page or prompt from silently reaching internal infrastructure.

rss_fetch reads RSS and Atom feeds through the same network and credential policy. It normalizes feed metadata and entries and supports conditional requests with ETag and Last-Modified validators.

Use these built-ins for normal APIs and feeds. Use Stateful Browser Tools when a source requires JavaScript rendering, a login flow, multiple tabs, or stateful interaction.

FRED Macro Data

FRED tools expose macroeconomic series to agents:

  • list_fred_series

  • get_fred_series

  • get_fred_latest

  • get_fred_snapshot

Set FRED_API_KEY so LumiBot can request FRED/ALFRED vintage observations using realtime parameters. LumiBot’s built-in FRED tools do not use public CSV fallbacks; macro tool output should either come from the official API or fail clearly.

News

If the active broker is Alpaca, LumiBot can use that broker connection for Alpaca/Benzinga news. If the active broker is not Alpaca, configure the news-only ALPACA_NEWS_API_KEY / ALPACA_NEWS_API_SECRET env vars instead. Generic Alpaca broker env vars are intentionally not used for news-only access, so news credentials do not confuse broker selection for Tradier, IBKR, or other brokers. In backtests, news tools should use the strategy datetime as the cutoff so the agent cannot read future headlines.

Memory

Memory tools write local SQLite and Parquet artifacts so agent decisions remain inspectable:

  • remember

  • search_memory

  • remember_proposal

  • remember_risk_note

  • remember_decision (trading-capable agents only)

  • remember_lesson

  • open_thesis

  • update_thesis

  • close_thesis

Memory works in both backtests and live runs. In a backtest, memory is part of the run artifact trail. In live trading, it can preserve context across iterations and restarts when the same memory directory is reused.

Use remember_proposal for research ideas and remember_risk_note for bear-case notes. Use remember_decision only for the final trading decision. When orders_submit_order submits an order, Lumibot automatically records an order.submitted memory event. Memory events and retrievals include agent_name and model_call_id when they came from an agent tool call.

Notifications

notify_user sends through configured notification providers. Telegram is the first built-in provider. Backtests keep notifications disabled by default, but you can explicitly opt in when testing notification behavior.

Point-In-Time Safety

The built-in research tools are designed around backtest/live parity:

  • indicators return current-bar values only

  • SEC filings are gated by filed or accepted datetime

  • FRED backtests use vintage observations when FRED_API_KEY is available

  • news tools use the strategy datetime as the cutoff

Lumibot point-in-time research tools

This lets agents research during a backtest without accidentally looking into the future.

Managed model families

With managed AI configured, a strategy may select a reviewed family such as google/gemini-pro, google/gemini-flash, google/gemini-flash-lite or openai/luna. The gateway resolves that family to one exact model on the first request. LumiBot keeps that model for the entire decision, including native tool continuations. Later decisions may use a newly reviewed mapping. For reproducible historical experiments, use an exact model id instead.

Family names require a compatible managed gateway. They are not aliases to send directly to a provider. BYOK execution continues to require an exact provider model id; LumiBot does not ignore personal keys or switch billing routes when authentication fails. Historical indicator windows —————————-

get_indicator and each get_indicators request accept optional start and end ISO timestamps with timezone offsets. Supply both together. The inclusive end cannot exceed strategy time. Only bars inside the window are used, including warmup; an insufficient window returns null, not a zero signal. For example, use separate result IDs and January/February bounds for independent monthly calculations. Source adapters retain ownership of bar completion.