Models
Pass a model when you create the agent, or per session. If you omit model, libfx uses fx's built-in default, an AI Gateway model. On AI Gateway, any model it lists works. ChatGPT plans, Grok plans, and custom providers need a model of their own; see Providers.
Find a model
import { listModels } from 'libfx'
const apiKey = process.env.AI_GATEWAY_API_KEY
if (!apiKey) throw new Error('Set AI_GATEWAY_API_KEY')
const models = await listModels({ apiKey })
console.log(models)
listModels() returns AI Gateway's language model ids, sorted. Pass one as model:
createFxAgent({ model: 'anthropic/claude-haiku-5.5' })
To configure the model, group its id and options:
createFxAgent({ model: { id: 'anthropic/claude-opus-5.5', effort: 'high', fast: true } })
Choose a model that supports the effort and fast mode you request. libfx checks these settings against the model before the prompt reaches it. On an agent, a setting the model doesn't support ends the turn with the stop reason error, and result.error.code names the setting, such as LIBFX_MODEL_UNSUPPORTED_EFFORT. createFxEngine() rejects with that code instead.
A string model id still works. Top-level effort, fast, and ultrafast are deprecated and can't be mixed with a model object.
Set reasoning effort
Set model.effort, such as effort: 'high'. The levels depend on the model. If the level is unsupported, the turn fails with LIBFX_MODEL_UNSUPPORTED_EFFORT. Omit effort or use 'default' to leave the choice to the model.
Enable fast mode
Set fast: true inside the model object for a model with a fast lane. On a model without one, the turn fails with LIBFX_MODEL_UNSUPPORTED_FAST.
Enable Ultrafast
Ultrafast requests OpenAI's higher-priced service tier through AI Gateway. Review the model's Gateway pricing before you send a prompt. Both backends require the catalog to advertise Ultrafast prices for that model.
import { createFxAgent } from 'libfx'
const agent = createFxAgent({
model: { id: 'openai/gpt-6-astra', ultrafast: true },
})
model.ultrafast is a strict boolean and defaults to false. With true, libfx checks that the model is eligible, and on one that isn't, the turn fails with LIBFX_MODEL_UNSUPPORTED_ULTRAFAST. No list of models is built in: an OpenAI model qualifies when its Gateway catalog entry includes the tier's pricing.
Ultrafast takes precedence over fast mode. Omit fast when you choose Ultrafast; if you set both, libfx validates both. Setting it on a request doesn't confirm the tier you were served. An older native addon without Ultrafast support rejects the option with LIBFX_NATIVE_CAPABILITY_UNAVAILABLE instead of ignoring it.
Change models
Each session can choose its own model. The setting applies to the turns that session object starts, and the conversation carries over:
agent.session(sessionId, { model: { id: 'anthropic/claude-opus-5.5', effort: 'high' } })
Each prompt stores the settings of the session object that sent it, so its turn uses them on whichever server runs it. A later agent.session(sessionId) without them uses the agent's model, so you supply these settings again each time you open it. With createFxEngine(), save a checkpoint and restore it into a new engine with the new model.
Supply the catalog
libfx reads AI Gateway's model catalog to check effort, fast, and Ultrafast settings. Behind a proxy that forwards only chat requests, pass the catalog yourself, and the agent won't fetch it:
createFxAgent({ modelCatalog: await fetchCatalogFromYourBackend() })
modelCatalog takes the catalog response's { data } or its entries.