bx-ai: Models & Providers

BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

aiModel() BIF

// Signature (all arguments optional)
aiModel( provider, apiKey, tools=[], params={}, options={}, middleware=[], skills=[], mcpServers=[] )

mcpServers takes URLs, HTTP or stdio ({ command: [ ... ] }) config structs, or MCP() clients, same as aiAgent(). The model also has withMCPServer(), withMCPServers() and closeMCPServers(). See bx-ai-mcp.

aiModel() and aiService() also take profile: "fast" to use a named, pre-configured combination of provider, model, params and key. See bx-ai-profiles.

Returns a reusable model runnable used in pipelines, agents, and direct calls. Always use named arguments beyond the first.

// Uses the default provider from module settings
model = aiModel()

// Specific provider
model = aiModel( provider: "claude" )

// With default parameters (applied to every call on this model)
model = aiModel(
    provider: "openai",
    params  : {
        model      : "gpt-4o",
        temperature: 0.7,
        max_tokens : 2000
    },
    options : { timeout: 60 }
)

Available Providers

The valid provider keys are exactly: bedrock, cartesia, claude, cloudflare, cohere, deepseek, docker, elevenlabs, gemini, grok, groq, huggingface, minimax, mistral, mock, ollama, openai, openai-compatible, openrouter, perplexity, voyage. Any other key throws ProviderNotSupported (unless another module answers the onMissingAiProvider announcement).

Capabilities come from each service's static CAPABILITIES array. Default model is the chat model in the service's default params.

Check capabilities at runtime with aiService( "openai" ).getCapabilities() or .hasCapability( "stream" ). For speech, streaming speech and transcription, see the bx-ai-audio skill.

API Key Resolution

aiService() resolves the key in this order:

1. apiKey passed in the call (options.apiKey, or the apiKey argument of aiModel())
2. Environment/system setting <PROVIDER>_API_KEY, where the provider key is upper-cased as is (OPENAI_API_KEY, CLAUDE_API_KEY, GEMINI_API_KEY, GROQ_API_KEY). Note it is the BoxLang provider key, so Claude is CLAUDE_API_KEY, not ANTHROPIC_API_KEY.
3. The module-level apiKey setting

Extra requirements:

• cloudflare: account ID from the accountId option, else the CLOUDFLARE_ACCOUNT_ID environment setting. Missing it throws an error on use.
• bedrock: uses AWS credentials, not a plain API key. Options: region, awsAccessKeyId, awsSecretAccessKey, awsSessionToken, modelId, baseURL, bearerToken. Falls back to AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION / AWS_DEFAULT_REGION, AWS_BEARER_TOKEN_BEDROCK, and ECS/EKS container credentials. configure( "string" ) sets the modelId, not a key.

aiChat( "Hi", {}, { provider: "cloudflare", accountId: "abc123" } )

Module-Level Config (Recommended)

Settings live under modules.bxai.settings in boxlang.json. Top-level keys include provider (default provider, default "openai"), apiKey, defaultParams, timeout (default 90), returnFormat and the log* flags. Per-provider defaults go in providers.<providerKey> with params and options sub-structs.

{
  "modules": {
    "bxai": {
      "settings": {
        "provider": "claude",
        "defaultParams": { "temperature": 0.7 },
        "providers": {
          "openai": {
            "params" : { "model": "gpt-4o" },
            "options": { "timeout": 60 }
          },
          "claude": {
            "params": { "model": "claude-sonnet-5", "max_tokens": 2048 }
          }
        }
      }
    }
  }
}

Merge order for params: defaultParams, then providers.<key>.params, then per-call params. Prefer env vars (OPENAI_API_KEY, ...) over hardcoding keys in settings.

// No apiKey needed when env vars or settings supply it
result = aiChat( "Hello" )
model  = aiModel( provider: "claude" )
agent  = aiAgent( name: "Bot", model: aiModel( provider: "openai" ) )

aiService(): Direct Provider Access

// aiService( provider, options={} ): returns a configured provider service instance.
// options may be a struct or a simple API key string.
service = aiService( "openai" )
service = aiService( provider: "openai", options: { apiKey: "sk-..." } )

service.getName()
service.getCapabilities()           // array of capability strings
service.hasCapability( "stream" )   // boolean

There is no getProviders(), getProvider() or setDefaultProvider(). To change the default provider set the provider module setting. Use aiModel() for pipelines and agents; use aiService() when you need the raw provider.

Switching Models per Call

// Override model per request via params
result = aiChat(
    "Complex reasoning task",
    { model: "gpt-4o", temperature: 1 },
    { provider: "openai" }
)

Audio

Speech (aiSpeak, aiSpeakStream) and transcription (aiTranscribe) are covered in the bx-ai-audio skill. Providers with audio capabilities are marked in the table above.

Common Pitfalls

• aiModel( "gpt-4o" ) is WRONG: the first argument is the provider key, not a model name
• aiModel( provider: "openai", params: { model: "gpt-4o" } ) is correct
• Never hardcode API keys in source code: use environment variables
• Use only the provider keys listed above; they are lowercase
• Configure defaults once in module settings for centralized management