Models

Pass a model ID when creating the agent. If you omit model, libfx uses its built-in default. Model requests in libfx 0.0.13 go through AI Gateway; use the key from Quick start.

Find a model

import { listModels } from 'libfx'

const models = await listModels({ apiKey: process.env.AI_GATEWAY_API_KEY })
console.log(models)

listModels() returns the available model IDs. Pass one as model in createFxAgent({ apiKey, model }).

To configure the model, group its ID and options together:

model: { id: 'your-model-id', effort: 'high', fast: true }

Choose a model that supports the requested effort and fast mode. A string model ID still works. Top-level effort and fast are deprecated and cannot be mixed with a model object.

Set reasoning effort

Set model.effort, such as effort: 'high' inside the model object. Available levels depend on the selected model. If the level is unsupported, creation fails with LIBFX_MODEL_UNSUPPORTED_EFFORT and lists the supported levels.

Omit model.effort or use 'default' to leave the choice to the model.

Enable fast mode

Set fast: true inside the model object for a model that supports a fast lane. Creation fails with LIBFX_MODEL_UNSUPPORTED_FAST if the selected model does not support it.

Enable Ultrafast

Ultrafast requests OpenAI's higher-priced service tier through AI Gateway. Review the selected model's Gateway pricing before sending a prompt. Both the native and WebAssembly backends require the catalog to advertise Ultrafast prices for that model.

import { createFxAgent } from 'libfx'

const agent = await createFxAgent({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  model: { id: 'openai/gpt-6-astra', ultrafast: true },
})

try {
  const turn = agent.prompt('Review this change')
  for await (const event of turn) {
    if (event.type === 'text_delta') process.stdout.write(event.delta)
  }
  await turn.result
} finally {
  await agent.close()
}

model.ultrafast is a strict boolean and defaults to false. With true, creation checks eligibility and rejects unsupported models with LIBFX_MODEL_UNSUPPORTED_ULTRAFAST, plus model and capability: 'ultrafast'. There is no hardcoded Astra-only list: another OpenAI model, including Sol, qualifies only when its Gateway catalog supplies the tier's pricing.

Ultrafast takes precedence over Fast on the request. Omit fast when choosing Ultrafast; if you supply both, libfx validates both model capabilities. A request setting is not served-tier confirmation, and fx emits a warning when Gateway does not confirm Ultrafast.

With a string or omitted model, a top-level ultrafast boolean is also accepted. Do not combine it with a model object. Use a libfx release and native addon that support the option; older addons reject an explicitly supplied option with LIBFX_NATIVE_CAPABILITY_UNAVAILABLE rather than silently ignoring it.

Change models

Save a checkpoint, then create a new agent with that checkpoint and the new model options. The checkpoint preserves the conversation; you supply these settings again.