Agent Built-In Tools ==================== .. meta:: :description: LumiBot agents are useful because they can inspect the same strategy state that your Python code can inspect. 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. .. code-block:: python 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. .. image:: ../docs/assets/ai_committee/docs_tool_permissions.png :alt: 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. .. _agents-network-permissions: Network Permissions ------------------- The outbound network tools (``http_request``, ``read_document``, ``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``: .. code-block:: python 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. If one listed expiration has unavailable Greeks or quotes, the agent checks other listed expirations allowed by those constraints before declaring that data is unavailable. All legs are selected and verified for the chosen structure. Use one expiration when the structure requires it. Calendar legs may use distinct listed expirations only when the user or active rules allow them, without relaxing those limits. For stocks, a pending exit already owns that position change. A due exit condition or a limit away from the current market does not authorize replacing it. The agent changes an existing order only when the user's rules explicitly require that change. The final decision explains how the observed pending quantity already covers the intended position change and why another order would duplicate it. Lookback rules use the requested number of the latest completed bars. The reported indicator and date window must match the selected tool result. 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. - Broker price data often has no market indexes (Alpaca has no VIX). When a price tool has no data for an index such as VIX, VXN, OVX, GVZ, SPX or DJIA, its result includes a ``fred_hint`` naming the FRED series with the daily close (the VIX is ``VIXCLS``). ``get_fred_latest`` returns only what was published by the strategy date, so it is safe in backtests. 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 :doc:`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, Documents, 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. ``read_document`` reads any file or page at a URL: PDF, Word (``.docx``), Excel (``.xlsx``), CSV, tab-separated text, JSON, HTML, and ZIP archives (it lists and reads every file inside). An HTML page comes back as text plus every link on it, so an agent can find a report on a website and follow its link. ``find`` keeps only the lines that contain a word, and ``start`` with the returned ``next_start`` pages through long text. Every table in the file (a CSV, an Excel sheet, a table file inside a ZIP) is loaded for ``duckdb_query``, so the agent filters and adds up rows with SQL instead of by hand. A ZIP that unpacks to more than 100 MB is refused; the same limit applies to Word and Excel archives. Tables with the same label receive distinct names so earlier reads remain queryable. A malformed CSV/TSV retains its text and returns ``table_error`` instead of silently dropping rows. No tool is built for one website: the :doc:`agents_example_nancy_pelosi_trading_bot` reads the House Clerk's yearly ZIP index and PDF reports with ``read_document``. The ``web-documents`` skill tells agents how, including the backtest rule: use each document's own date and skip anything dated after the backtest time. .. code-block:: python self.agents.create( name="researcher", allow_trading=False, allow_network=True, system_prompt="Read https://example.com/reports/2025.zip and total the amounts by ticker.", ) ``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 :doc:`agents_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. DuckDB And Documentation Search ------------------------------- Agents can use DuckDB for structured analysis instead of asking the model to reason over raw tables inside the prompt. Documentation search tools let the agent inspect LumiBot usage patterns when it needs framework guidance. 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 Evidence packets retain each returned dataset ID beside its source, dates and query window. Attribute an aggregate to a tool only after the tool returns that aggregate; rows of individual prices are not a calculated average. When selecting document links in a backtest, filter by publication date before sorting or limiting the rows, then inspect the date before opening each link. Establish this eligibility before reading the linked document; opening a later document and then discarding its contents has already crossed the time boundary. For opening option packages, verify the standard leg topology before pricing. A reversed spread changes the structure; recheck buy/sell sides and strikes when the calculated debit or credit contradicts the intended package. Closing sides continue to come from actual signed positions. .. image:: ../docs/assets/readme/lumibot_point_in_time_tools.png :alt: 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.