3.2.0
BoxLang AI Module 3.2.0 — Image Generation, Web Search, Fluent Audio Builders, Agent Registry, MCP Observability & more.
Released: May 2026
BoxLang AI 3.2.0 introduces image generation (aiImage()), full web search integration (aiWebSearch() and aiWebSearchAsync()), a fluent builder API for all audio BIFs, the Agent Registry for centralized agent management, MCP server pause/resume, MCP client stats & observability, and major MCP server analytics improvements.
✨ New Features
🖼️ Image Generation — aiImage()
Generate images from text prompts using any provider that supports text-to-image generation.
aiImage( prompt, params, options )
Generate one or more images from a text description
Provider Support:
OpenAI
gpt-image-1 (default), DALL-E models
OPENAI_API_KEY
Gemini
imagen-3.0-generate-008
GEMINI_API_KEY
Grok / xAI
grok-2-image
GROK_API_KEY
OpenRouter
FLUX Schnell (default), many others
OPENROUTER_API_KEY
// Generate an image and save to file
aiImage( "A futuristic cityscape at sunset" )
.saveToFile( "/images/cityscape.png" )
// Generate with custom parameters
response = aiImage(
"A watercolor painting of a mountain lake",
{ n: 2, size: "1024x1024", quality: "hd" },
{ provider: "openai" }
)
// Get image as data URI for embedding in HTML
dataURI = response.toDataURI()AiImageResponse Methods:
hasImages()
boolean
true if images are present
getCount()
numeric
Number of generated images
getFirstURL()
string
URL of the first image
getFirstBase64()
string
Base64 of the first image
getRevisedPrompt()
string
Provider's revised prompt (if any)
saveToFile( path )
string
Save first image to file
saveAllToDirectory( dir )
array
Save all images to directory
toDataURI()
string
Data URI for HTML embedding
getMimeType()
string
MIME type of the image
toStruct()
struct
Metadata struct
generateImage@bxai Agent Tool: Auto-registered in the global tool registry. Generates an image from a text prompt and returns the absolute file path.
Documentation: Image Generation
🔍 Web Search Tools — aiWebSearch() and aiWebSearchAsync()
BoxLang AI now includes a unified web search system with normalized results and provider abstraction.
aiWebSearch( query, options )
Synchronous web search across configured providers
aiWebSearchAsync( query, options )
Async web search returning a BoxFuture
Providers:
http
none
URL fetching / parsing, no external API key required
brave
BRAVE_API_KEY
Privacy-focused search with country/language filters
google
GOOGLE_API_KEY + GOOGLE_SEARCH_ENGINE_ID
Google Custom Search support
tavily
TAVILY_API_KEY
Retrieval-focused search for AI agents
exa
EXA_API_KEY
Semantic and neural search modes
Result format: every provider returns the same fields: title, url, snippet, publishedDate, domain, score, thumbnail, language.
Auto-Registered Tool: webSearch@bxai is registered at module startup and available via aiToolRegistry().
Documentation: Web Search Tools
🎤 Fluent Builder API for Audio BIFs
aiSpeak(), aiTranscribe(), and aiTranslate() now support a fluent builder API. Calling any of these BIFs with no arguments returns the request object for method chaining.
aiSpeak() Fluent Builder
Builder Methods:
of( text )
Set the text to synthesize
.text( text )
Alias for of()
.model( name )
Set the TTS model
.provider( name )
Set the provider
.apiKey( key )
Set the API key
.voice( name )
Set the voice
.male() / .female()
Gender shortcut (resolved per provider)
.speed( n )
Set playback speed
.instructions( text )
Set voice instructions
.outputFile( path )
Set output file path
.asMP3() / .asWav() / .asFlac() / .asOpus() / .asPCM()
Format shortcuts
.withParams( struct )
Set provider params
.withOptions( struct )
Set module options
.withLogging()
Enable request/response logging
.speak()
Execute and return AiSpeechResponse
aiTranscribe() Fluent Builder
Builder Methods:
of( audio )
Static factory — set audio input
.file( path )
Set audio file path
.url( url )
Set audio URL
.data( binary )
Set raw binary audio data
.model( name )
Set the STT model
.provider( name )
Set the provider
.apiKey( key )
Set the API key
.language( code )
Set input audio language (BCP-47)
.inputFormat( fmt )
Set input audio format
.withWordTimestamps()
Enable word-level timestamps
.withSegmentTimestamps()
Enable segment-level timestamps
.withTimestamps()
Enable all timestamps
.diarize( bool )
Enable speaker diarization
.asJSON() / .asText() / .asVerboseJSON() / .asSRT() / .asVTT()
Output format shortcuts
.withParams( struct )
Set provider params
.withOptions( struct )
Set module options
.withLogging()
Enable request/response logging
.transcribe()
Execute transcription
.translate()
Execute translation (audio → English)
aiTranslate() Fluent Builder
Documentation: Audio — Speech & Transcription
🤖 Agent Registry
New AIAgentRegistry singleton (access via aiAgentRegistry() BIF) for centralized agent discoverability, observability, and analytics.
Registry API:
register( agent, module )
Register an agent with optional module namespace
unregister( key )
Remove agent by key
unregisterByModule( module )
Remove all agents from a module
resolveAgents( array )
Resolve mixed array of string keys and AiAgent instances
listAgents()
Return struct of all registered agents
getAgentInfo( key )
Return { name, description, module } for a key
New Events: onAIAgentRegistryRegister, onAIAgentRegistryUnregister
⏸️ MCP Server Pause/Resume
MCPServer now supports pausing and resuming without destroying configuration.
pause()— firesonMCPServerPauseinterception pointresume()— firesonMCPServerResumeinterception pointisPaused()— returnstrueif currently pausedgetSummary()now includespausedbooleanNew error code:
SERVER_PAUSED: -32005
📊 MCP Server Observability & Analytics
Major improvements to MCP server monitoring:
Thread-safe counters: All stats counters now use named locks for concurrent safety
Security failure tracking: Dedicated counters for auth failures, API key rejections, body-size violations
Paused-request stats: Rejected requests now tracked in stats
Per-tool error tracking:
byTool[name].errorsanderrors.byToolroll-upActive concurrent request counter:
activeRequeststracked with increment/decrementRequests-per-minute rate:
getSummary()includesrequestsPerMinuteX-Request-ID correlation: Request IDs echoed in response headers and event payloads
onMCPErrorfor METHOD_NOT_FOUND: Now fires the interception point
📈 MCP Client Stats & Observability
MCPClient now tracks internal usage and performance metrics.
Stats API:
getStats()
Full stats struct with per-operation, per-tool, per-URI breakdowns
getSummary()
Lightweight summary with totalCalls, successRate, avgResponseTime
resetStats()
Reset all counters to zero
New Events: onMCPClientRequest, onMCPClientResponse, onMCPClientError
🐛 Fixed
ClosureTool.doInvoke(): MCP clients sending JSON fields as real objects/arrays (instead of pre-stringified JSON) no longer cause "Can't cast Struct to a string" errors. The fix walks declared parameters andjsonSerialize()s any non-simple value whose declared type isstring.
📦 Module Configuration Updates
Image Settings
New image settings block in boxlang.json:
New Interception Points
40 → 50 total interception points. New events in 3.2.0:
42
beforeAIImageGeneration
Before image generation request
43
afterAIImageGeneration
After image generation response
44
onAIImageRequest
Image request object created
45
onAIImageResponse
Image response received
46
onAIAgentRegistryRegister
Agent registered
47
onAIAgentRegistryUnregister
Agent unregistered
48
onMCPServerPause
MCP server paused
49
onMCPServerResume
MCP server resumed
50
onMCPClientRequest
MCP client HTTP request
51
onMCPClientResponse
MCP client HTTP response
52
onMCPClientError
MCP client HTTP error
🔄 Migration Guide
Audio BIFs — Fluent Builder
The traditional aiSpeak( text, params, options ) syntax continues to work unchanged. The fluent builder is an additional option — no migration required.
Agent Registry
The aiAgent() BIF gains two new optional parameters:
register: false(default) — set totrueto auto-register the agentmodule: ""— module namespace for the registry key
Existing agent creation code works unchanged.
MCP Server
MCPServer gains pause(), resume(), and isPaused() methods. Existing server code works unchanged.
Last updated