Skip to the page
INTEGRATIONS/LLM ADAPTERS

LLM adapters

An adapter runs an agent built in an LLM framework inside a simulated market on your machine. tradefloor sends the framework a JSON observation and the framework answers with a decision. tradefloor then checks the decision, places its orders in the simulation and scores the run. An adapter is an ordinary agent with an act method, so it runs under tf.evaluate, tf.rank and World.

Three ways to connect a model

  • LLM adapters (this page) run the model inside a simulated market in your own Python process, and its decisions become orders there.
  • The local MCP server gives an MCP client, such as Claude Code or a CrewAI agent, simulation and evaluation tools, and sessions where the model sends orders step by step to a simulated market the server keeps in memory.
  • The hosted app, in beta, lets a model or a bot place orders in saved markets on app.tradefloor.dev over MCP, an HTTP API or an Alpaca-shaped API.

Setup

Each framework is an optional extra. tradefloor needs Python 3.11 or later.

FrameworkInstallModuleMinimum version
A plain Python functionpip install tradefloortradefloor.integrations.callablenone
OpenAI Agents SDKpip install "tradefloor[openai-agents]"tradefloor.integrations.openai_agentsopenai-agents 0.22
PydanticAIpip install "tradefloor[pydantic-ai]"tradefloor.integrations.pydantic_aipydantic-ai-slim 2.36
LangGraphpip install "tradefloor[langgraph]"tradefloor.integrations.langgraphlanggraph 1.2
FinRobotpip install "tradefloor[finrobot]"tradefloor.integrations.finrobotPython 3.11 exactly

You don't need any of the extras to replay a recorded run.

A first run with no API key

The callable adapter wraps any function that takes the observation payload and returns a decision. Start with a function that answers without a model. It's the fastest way to check the loop before you set up a key or an extra.

import json

import tradefloor as tf
from tradefloor.integrations.callable import callable_agent

def ask_model(payload):
    # stands in for a model call: the payload is what a model is shown
    first = payload["assets"][0]
    order = {"symbol": first["symbol"], "side": "BUY", "quantity": 100}
    return json.dumps({"actions": [order], "rationale": "add 100 a day"})

adapter = callable_agent(ask_model)
market = tf.Universe.random(12, seed=4242)
card = tf.evaluate({"model": adapter}, seed=4242, universe=market, days=5)["model"]
print(card)
print(len(adapter.record), "decisions")
Scorecard('model', pnl=812, return=+0.08%, trades=5, impact=+0.19bps, sharpe=n/a (short run), vol=0.3%, in_market=100%, exposure=0.02x)
5 decisions

Replace the body of ask_model with a call to your model, and parse its text into a decision with postprocess=, as in Recording and replay. adapter.record has one entry per decision with the payload, the exact input, the raw response, the validated decision and the orders.

Framework pages

Each framework has a page with the install line, a first run and the versions it was tested with. None of the first runs needs an API key. The OpenAI Agents SDK and PydanticAI pages use a test model the framework ships, and the LangGraph page uses a plain rule where the model would go:

Decisions and model calls

An adapter asks its framework for a decision every every decision steps, 6 by default. obs.step counts steps across the whole run, so with the default 6 steps a day that's one decision a simulated day, at each day's first step. With steps_per_day=3 the default asks every second day. On the steps between decisions the adapter records the prices it saw and returns no orders.

One decision can cost several calls to the model provider. A 20-day run is 20 decisions and can be many more provider calls:

  • A framework turn is one model call, and an agent that calls tools takes several turns per decision. The OpenAI Agents adapter caps a decision at max_turns=6, and the PydanticAI adapter at request_limit=8 requests.
  • PydanticAI retries a schema violation inside its own loop, and each retry is another request. The OpenAI Agents SDK 0.22 makes no client-side retry on a malformed answer.
  • A LangGraph graph makes whatever calls its nodes make.

The observation payload

The framework only ever sees the serialized payload. tradefloor builds it field by field from an allowlist, and the observation object never reaches the framework:

KeyWhat it holds
step, day, steps_per_dayThe clock. step counts the whole run.
macroThe published figures: the VIX, the policy rate, the corporate bond yield, inflation and the business-cycle phase as announced, late.
assetsPer name: the symbol, price, one-day and five-day returns and volatility from the prices the adapter has seen, the best bid and ask, average daily volume, max_order_shares (the participation cap), the position held, and any fundamentals you pass with fundamentals=. On a model that pays dividends, also dividend, and on one that runs an earnings calendar, also next_earnings_in_sessions.
portfolioCash, net worth, leverage, max_leverage, buying_power and the waiting limit orders.

dividend is the cash per share the name went ex for at that day's open, and 0.0 on a day it paid nothing. next_earnings_in_sessions is the number of sessions to the name's next earnings report. pt-v21 has both, and no earlier preset has either:

import json

import tradefloor as tf
from tradefloor.integrations.callable import callable_agent
from tradefloor.integrations.common import OBSERVATION_SCHEMA_VERSION

def ask_model(payload):
    return json.dumps({"actions": []})

market = tf.Universe.random(12, seed=4242)
for preset in ("pt-v21", "pt-v20"):
    adapter = callable_agent(ask_model)
    tf.evaluate({"model": adapter}, seed=4242, universe=market, days=5, model=preset)
    first = adapter.record[-1]["payload"]["assets"][0]
    extra = {k: first[k] for k in ("dividend", "next_earnings_in_sessions") if k in first}
    print(preset, extra)
print("payload version:", OBSERVATION_SCHEMA_VERSION)
pt-v21 {'dividend': 0.0, 'next_earnings_in_sessions': 28}
pt-v20 {}
payload version: 3

From tradefloor 0.11.0 the payload is version 3. On a model that lists contracts, as pt-v22 does, it adds index, futures, margin and options, and on every other model it is version 2's to the byte. Version 2, from 0.10.0, added these two keys to version 1, used on 0.8.5 to 0.9.x. On a preset without dividends or an earnings calendar the payload matches version 1, and a recording made under version 1 still replays there. It doesn't replay on pt-v21 or pt-v22, where the payloads have the new keys. A recording names its payload version in meta["observation_schema_version"].

At any access level, the payload has no fair value, no factor attribution and no macro path the run hasn't reached. The adapter's act gets the read-only market view by default, or the live engine under trusted_agents=True (see What the agent sees). The framework still gets only the payload.

The decision is a list of actions. Each has a symbol, a side (BUY, SELL, HOLD or CANCEL), a positive quantity in shares, and an optional limit_price that makes it a limit order. A bad action is refused on its own and listed in the scorecard's errors. An order over max_order_shares, 2% of the name's average daily volume by default, is cut to the cap, and an order below one share is dropped. Bringing an LLM agent has the full contract.

Reference

LLM adapters and MCP has every adapter's signature, the shared layer, error types, replay rules and the framework version each adapter was written against. When a run fails or makes no trades, Troubleshooting lists the messages and fixes.

Next steps