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.