Event System

Intercept, monitor, and customize AI operations at every stage with the module's 70 interception points.

The BoxLang AI module provides a comprehensive event system that allows you to intercept, monitor, and customize AI operations at various stages. These events give you fine-grained control over the AI lifecycle, from object creation to request/response handling.

🔍 Overview

The event system allows you to monitor, modify, validate, audit, secure, and customize AI operations without modifying core code.

All Available Events

#	Event	When Fired	Key Data
1	onAIMessageCreate	Message template created	message
2	onAIChatRequestCreate	Chat request object instantiated	aiRequest
4	onAIProviderCreate	Provider instance created	provider
5	onMissingAiProvider	Provider not found	provider, options
6	onAIModelCreate	Model runnable created	model, service
7	onAITransformerCreate	Transform runnable created	transform
8	onAIAgentCreate	Agent instance created	agent, name
9	beforeAIAgentRun	Before agent execution	agent, input
10	afterAIAgentRun	After agent execution	agent, result
11	beforeAIModelInvoke	Before model execution	model, request
12	onAIChatRequest	Before chat HTTP request	dataPacket, aiRequest, provider
13	onAIChatResponse	After chat HTTP response	response, rawResponse, provider
14	afterAIModelInvoke	After model execution completes	model, request, results
15	beforeAIEmbed	Before embedding generation	embeddingRequest, service
16	onAIEmbedRequest	Before embedding HTTP request	dataPacket, embeddingRequest, provider
17	onAIEmbedResponse	After embedding HTTP response	response, rawResponse, provider
18	afterAIEmbed	After embedding generation	embeddingRequest, service, result
19	onAIToolCreate	Tool created	tool, name, description
20	beforeAIToolExecute	Before tool execution	tool, name, arguments
21	afterAIToolExecute	After tool execution	tool, results, executionTime
22	onAiLoaderCreate	Document loader created	loader, type
23	onAiMemoryCreate	Memory instance created	memory, type
24	beforeAIPipelineRun	Before pipeline starts	sequence, stepCount, input
25	afterAIPipelineRun	After pipeline completes	sequence, result, executionTime
26	onAIError	Error occurs	error, errorMessage, provider, canRetry
27	onAIRateLimitHit	Rate limit detected (429)	provider, statusCode, retryAfter
28	onAITokenCount	Token usage available	provider, operation, model, promptTokens, completionTokens, totalTokens, aiRequest, usage, timestamp
29	onMCPServerCreate	MCP server instance created	server, name, description
30	onMCPServerRemove	MCP server instance removed	name
31	onMCPRequest	Before processing MCP request	server, requestData, serverName
32	onMCPResponse	After processing MCP response	server, response, requestData
33	onMCPError	Exception during MCP operations	server, context, exception, request details
34	beforeAISpeech	Before TTS request is sent	speechRequest, service
35	afterAISpeech	After TTS response received	speechRequest, service, result
36	beforeAITranscription	Before STT request is sent	transcriptionRequest, service
37	afterAITranscription	After STT response received	transcriptionRequest, service, result
38	beforeAITranslation	Before audio translation request	transcriptionRequest, service
39	afterAITranslation	After audio translation response	transcriptionRequest, service, result
40	onHybridMemoryAdd	Message added to HybridMemory	memory, message
41	onVectorSearch	Vector semantic search runs	memory, query, limit, results
42	beforeAIImageGeneration	Before image generation request	imageRequest, service
43	afterAIImageGeneration	After image generation response	imageRequest, service, result
44	onAIImageRequest	Image request object created	imageRequest
45	onAIImageResponse	Image response received	response, rawResponse, provider
46	onAIAgentRegistryRegister	Agent registered	agent, key, module
47	onAIAgentRegistryUnregister	Agent unregistered	key, module
48	onMCPServerPause	MCP server paused	server, name
49	onMCPServerResume	MCP server resumed	server, name
50	onMCPClientRequest	MCP client HTTP request	client, baseURL, operation, name
51	onMCPClientResponse	MCP client HTTP response	client, baseURL, operation, response
52	onMCPClientError	MCP client HTTP error	client, baseURL, operation, error
53	beforeAIWebSearch	Before a web search query executes	provider, query, options
54	afterAIWebSearch	After a web search returns results	provider, query, results, cached
55	onAIWebSearchRequest	Before the search provider's HTTP request	provider, url, method, headers
56	onAIWebSearchResponse	After the search provider's HTTP response	provider, url, statusCode, response
57	onAIWebSearchError	A web search throws	provider, query, error
58	onAIMemorySummarize	A memory instance's summarize() completes	memory, key, type, userId, conversationId
59	onGatewayCreate	aiGateway() resolves or creates a gateway	gateway
60	onGatewayRegistryRegister	A gateway is registered into aiGatewayRegistry()	gateway, key, module
61	onGatewayRegistryUnregister	A gateway is removed from the registry	key, module
62	onAiDecisionStoreCreate	aiDecisionStore() creates a store instance	storeType, storeClass, storeConfig
63	onGatewaySessionCreate	aiGatewaySession() constructs a session	session
64	onGatewayConnect	A gateway's start() makes a real not-running → running transition	gateway
65	onGatewayDisconnect	A gateway's stop() makes a real running → not-running transition	gateway
66	onGatewayMessageReceived	A gateway's parseInbound() parses an inbound message	gateway, message, threadId, userId, conversationId
67	onGatewayMessageSent	A gateway's deliver() sends an outbound message	gateway, event, context, result, threadId
68	onAIAgentRunCancel	agent.cancelRun() actually affects a run in flight	agent, threadId, reason
69	onAIAgentRunSteer	agent.steerRun() actually affects a run in flight	agent, threadId, input

🔄 Event Lifecycle Diagram

📊 Event Categories

---

🔌 Event Interception

To listen to events, create an interceptor and register it in your module or application.

🏗️ Interceptor Architecture

Creating an Interceptor

// interceptors/AIMonitor.bx
class {

    function configure() {
        // Interceptor configuration
    }

    function onAIChatRequest( event, interceptData ) {
        // Your event handling logic
    }

    function onAIChatResponse( event, interceptData ) {
        // Your event handling logic
    }
}

Registering an Interceptor

For BoxLang Modules (in ModuleConfig.bx):

function configure() {
    interceptors = [
        {
            class: "interceptors.AIMonitor",
            properties: {}
        }
    ];
}

For Applications/Scripts (use BoxRegisterInterceptor() BIF):

// Application.bx or script
BoxRegisterInterceptor( "AIMonitor", "path.to.AIMonitor" );

📖 Reference: BoxRegisterInterceptor() Documentation

---

📡 Available Events

1. onAIMessageCreate

Fired when an AI message object is created via aiMessage().

When: Message template creation Frequency: Once per aiMessage() call

Event Arguments

Argument	Type	Description
message	AiMessage	The created message object

Example

function onAIMessageCreate( event, interceptData ) {
    var message = interceptData.message;

    // Log message creation
    writeLog(
        text: "AI Message created with #arrayLen( message.getMessages() )# messages",
        type: "info"
    );

    // Add default system message if none exists
    var messages = message.getMessages();
    if ( messages.isEmpty() || messages[1].role != "system" ) {
        message.system( "You are a helpful assistant" );
    }
}

---

2. onAIChatRequestCreate

Fired when an AI chat request object is created via aiChatRequest().

When: Chat request object instantiation Frequency: Once per aiChatRequest() call

Event Arguments

Argument	Type	Description
aiRequest	AiChatRequest	The created request object

#### Example

```java
function onAIChatRequestCreate( event, interceptData ) {
    var request = interceptData.aiRequest;

    // Add tracking metadata
    request.setParams({
        user: getAuthenticatedUser(),
        requestId: createUUID(),
        timestamp: now()
    });

    // Apply organization-wide defaults
    if ( !request.getParams().keyExists( "temperature" ) ) {
        request.setParam( "temperature", 0.7 );
    }
}

---

---

4. onAIProviderCreate

Fired when a provider/service instance is created.

When: After provider instantiation Frequency: Once per unique provider instance

Event Arguments

Argument	Type	Description
provider	IService	The created service instance

#### Example

```java
function onAIProviderCreate( event, interceptData ) {
    var service = interceptData.provider;

    // Configure provider-specific settings
    service.setTimeout( 60 );

    // Add custom headers
    service.setHeaders({
        "X-App-Version": getAppVersion(),
        "X-Environment": getEnvironment()
    });

    writeLog(
        text: "AI Provider created: #service.getProviderName()#",
        type: "info"
    );
}

---

5. onAIModelCreate

Fired when an AI model runnable is created via aiModel().

When: Model wrapper creation Frequency: Once per aiModel() call

Event Arguments

Argument	Type	Description
model	AiModel	The created model runnable
service	IService	The underlying service

#### Example

```java
function onAIModelCreate( event, interceptData ) {
    var model = interceptData.model;
    var service = interceptData.service;

    // Set default model parameters
    model.setParams({
        temperature: 0.7,
        max_tokens: 2000
    });

    // Track model creation
    logMetric( "ai.model.created", {
        provider: service.getProviderName(),
        timestamp: now()
    });
}

---

6. onAITransformerCreate

Fired when a transform runnable is created via aiTransform().

When: Transform function creation Frequency: Once per aiTransform() call

Event Arguments

Argument	Type	Description
transform	AiTransformRunnable	The created transform runnable

#### Example

```java
function onAITransformerCreate( event, interceptData ) {
    var transform = interceptData.transform;

    // Wrap transform with error handling
    var originalFn = transform.getTransformFn();
    transform.setTransformFn( function( input, params ) {
        try {
            return originalFn( input, params );
        } catch ( any e ) {
            logError( "Transform error: #e.message#" );
            return { error: true, message: e.message };
        }
    });
}

---

7. beforeAIModelInvoke

Fired before an AI model is invoked (before sending to provider).

When: Before model execution Frequency: Every model invocation

Event Arguments

Argument	Type	Description
model	AiModel	The model being invoked
request	AiChatRequest	The request being sent

#### Example

```java
function beforeAIModelInvoke( event, interceptData ) {
    var model = interceptData.model;
    var request = interceptData.request;

    // Validate request
    if ( arrayLen( request.getMessages() ) == 0 ) {
        throw( "Cannot invoke model with empty messages" );
    }

    // Add request tracking
    request.setMetadata({
        invokeTimestamp: now(),
        userId: getAuthenticatedUser()
    });

    // Cost estimation
    var estimatedTokens = estimateTokenCount( request.getMessages() );
    writeLog(
        text: "Model invocation: ~#estimatedTokens# tokens",
        type: "info"
    );
}

---

8. onAIChatRequest

Fired immediately before sending the HTTP request to the AI provider for chat operations.

When: Before chat HTTP request Frequency: Every chat API call (including streaming)

Event Arguments

Argument	Type	Description
dataPacket	Struct	The HTTP request data packet
aiRequest	AiChatRequest	The AI request object
provider	IService	The service making the request

#### Example

```java
function onAIChatRequest( event, interceptData ) {
    var dataPacket = interceptData.dataPacket;
    var request = interceptData.aiRequest;
    var provider = interceptData.provider;

    // Modify request before sending
    dataPacket.headers[ "X-Request-ID" ] = createUUID();

    // Log request details
    writeLog(
        text: "AI Request to #provider.getProviderName()#: " &
              "#arrayLen( request.getMessages() )# messages",
        type: "info",
        log: "ai-requests"
    );

    // Track costs
    trackAPICall( provider.getProviderName(), request.getParams() );

    // Add custom authentication
    if ( getSetting( "useCustomAuth" ) ) {
        dataPacket.headers[ "Authorization" ] = getCustomAuthToken();
    }
}

---

9. onAIChatResponse

Fired after receiving the HTTP response from the AI provider for chat operations.

When: After chat HTTP response Frequency: Every chat API call (including streaming)

Event Arguments

Argument	Type	Description
aiRequest	AiChatRequest	The original request
response	Struct	The deserialized response
rawResponse	Struct	The raw HTTP response
provider	IService	The service that made the request

#### Example

```java
function onAIChatResponse( event, interceptData ) {
    var response = interceptData.response;
    var request = interceptData.aiRequest;
    var provider = interceptData.provider;

    // Extract usage information
    if ( response.keyExists( "usage" ) ) {
        var usage = response.usage;
        logUsage({
            provider: provider.getProviderName(),
            promptTokens: usage.prompt_tokens ?: 0,
            completionTokens: usage.completion_tokens ?: 0,
            totalTokens: usage.total_tokens ?: 0,
            timestamp: now()
        });
    }

    // Modify response
    if ( response.keyExists( "choices" ) && arrayLen( response.choices ) > 0 ) {
        // Add metadata to response
        response._metadata = {
            processedAt: now(),
            provider: provider.getProviderName(),
            cached: false
        };
    }

    // Cache response
    if ( getSetting( "cacheResponses" ) ) {
        cacheResponse( request, response );
    }
}

---

10. afterAIModelInvoke

Fired after an AI model completes its invocation.

When: After model execution completes Frequency: Every model invocation

Event Arguments

Argument	Type	Description
model	AiModel	The model that was invoked
request	AiChatRequest	The request that was sent
results	Any	The results returned by the model

#### Example

```java
function afterAIModelInvoke( event, interceptData ) {
    var model = interceptData.model;
    var request = interceptData.request;
    var results = interceptData.results;

    // Calculate execution time
    var startTime = request.getMetadata().invokeTimestamp ?: now();
    var duration = dateDiff( "s", startTime, now() );

    // Log completion
    writeLog(
        text: "Model invocation completed in #duration#s",
        type: "info"
    );

    // Track metrics
    recordMetric( "ai.model.duration", duration );

    // Validate response
    if ( isStruct( results ) && results.keyExists( "error" ) ) {
        logError( "Model returned error: #results.error.message#" );
    }
}

---

11. onAIToolCreate

Fired when an AI tool is created via aiTool().

When: Tool creation Frequency: Once per aiTool() call

Event Arguments

Argument	Type	Description
tool	Tool	The created tool instance
name	String	Tool name
description	String	Tool description

#### Example

```java
function onAIToolCreate( event, interceptData ) {
    var tool = interceptData.tool;

    // Register tool in catalog
    registerToolInCatalog( tool.getName(), tool.getSchema() );

    // Validate tool configuration
    if ( !tool.getSchema().function.parameters.properties.isEmpty() ) {
        writeLog(
            text: "Tool created: #tool.getName()# with #structCount( tool.getSchema().function.parameters.properties )# parameters",
            type: "info"
        );
    }
}

---

12. beforeAIToolExecute

Fired immediately before a tool's callable function is executed.

When: Before tool execution Frequency: Every tool call

Event Arguments

Argument	Type	Description
tool	Tool	The tool being executed
name	String	Tool name
arguments	Struct	Arguments passed to the tool

#### Example

```java
function beforeAIToolExecute( event, interceptData ) {
    var tool = interceptData.tool;
    var args = interceptData.arguments;

    // Validate tool arguments
    validateToolArguments( tool.getName(), args );

    // Check permissions
    var user = getAuthenticatedUser();
    if ( !hasToolPermission( user, tool.getName() ) ) {
        throw( "User not authorized to execute tool: #tool.getName()#" );
    }

    // Rate limiting per tool
    if ( isToolRateLimited( tool.getName() ) ) {
        throw( "Tool rate limit exceeded: #tool.getName()#" );
    }

    // Log execution attempt
    writeLog(
        text: "Executing tool: #tool.getName()# with args: #serializeJSON(args)#",
        type: "info",
        log: "ai-tools"
    );
}

---

13. afterAIToolExecute

Fired immediately after a tool's callable function completes execution.

When: After tool execution Frequency: Every tool call

Event Arguments

Argument	Type	Description
tool	Tool	The tool that was executed
name	String	Tool name
arguments	Struct	Arguments passed to the tool
results	Any	Results returned by the tool
executionTime	Numeric	Execution time in milliseconds

#### Example

```java
function afterAIToolExecute( event, interceptData ) {
    var tool = interceptData.tool;
    var results = interceptData.results;
    var executionTime = interceptData.executionTime;

    // Log execution metrics
    logMetric( "ai.tool.execution", {
        tool: tool.getName(),
        duration: executionTime,
        success: !isNull( results ),
        timestamp: now()
    });

    // Track tool usage
    trackToolUsage( tool.getName(), executionTime );

    // Alert on slow tools
    if ( executionTime > 5000 ) {
        writeLog(
            text: "Slow tool execution: #tool.getName()# took #executionTime#ms",
            type: "warning"
        );
    }

    // Validate results
    if ( isNull( results ) || results == "" ) {
        writeLog(
            text: "Tool returned empty result: #tool.getName()#",
            type: "warning"
        );
    }
}

---

14. onAIError

Fired when an error occurs during AI operations (chat, embeddings, or streaming).

When: Before throwing provider errors Frequency: Every error condition

Event Arguments

Argument	Type	Description
error	Any	The error object/message from provider
errorMessage	String	Formatted error message
provider	IService	The provider where error occurred
operation	String	Operation type: "chat", "embeddings", "stream"
aiRequest	AiChatRequest	The request that caused the error (if available)
embeddingRequest	AiEmbeddingRequest	For embedding errors
canRetry	Boolean	Whether operation can be retried

#### Example

```java
class {

    property name="retryAttempts" default={};
    property name="maxRetries" default=3;

    function onAIError( event, interceptData ) {
        var error = interceptData.error;
        var provider = interceptData.provider.getProviderName();
        var operation = interceptData.operation;
        var canRetry = interceptData.canRetry;

        // Log the error
        writeLog(
            text: "AI Error in #provider# (#operation#): #interceptData.errorMessage#",
            type: "error",
            log: "ai-errors"
        );

        // Track error metrics
        recordMetric( "ai.error", {
            provider: provider,
            operation: operation,
            errorType: isStruct( error ) ? error.type : "unknown",
            timestamp: now()
        });

        // Implement retry logic
        if ( canRetry ) {
            var requestId = interceptData.aiRequest?.getMetadata().requestId ?: createUUID();
            var attempts = retryAttempts.keyExists( requestId ) ? retryAttempts[ requestId ] : 0;

            if ( attempts < variables.maxRetries ) {
                retryAttempts[ requestId ] = attempts + 1;

                writeLog(
                    text: "Retry attempt #attempts+1# of #maxRetries# for request #requestId#",
                    type: "warning"
                );

                // Wait before retry (exponential backoff)
                sleep( 1000 * ( 2 ^ attempts ) );

                // Signal to retry (implementation specific)
                interceptData.shouldRetry = true;
            } else {
                // Max retries exceeded
                writeLog(
                    text: "Max retries exceeded for request #requestId#",
                    type: "error"
                );

                // Cleanup retry tracking
                structDelete( retryAttempts, requestId );
            }
        }

        // Send alerts for critical errors
        if ( !canRetry || attempts >= maxRetries ) {
            sendErrorAlert({
                provider: provider,
                operation: operation,
                error: interceptData.errorMessage,
                timestamp: now()
            });
        }
    }
}

---

15. onAIRateLimitHit

Fired when a provider returns a 429 (rate limit) HTTP status code.

When: When rate limit is detected Frequency: Every rate limit response

Event Arguments

Argument	Type	Description
provider	IService	The provider that hit rate limit
operation	String	Operation type: "chat", "embeddings"
statusCode	String	HTTP status code (429)
errorData	Struct	Error response from provider
aiRequest	AiChatRequest	The request that hit the limit
retryAfter	String	Retry-After header value (if present)

#### Example

```java
class {

    property name="rateLimitCooldowns" default={};

    function onAIRateLimitHit( event, interceptData ) {
        var provider = interceptData.provider.getProviderName();
        var retryAfter = interceptData.retryAfter;

        // Parse retry-after header (seconds or HTTP date)
        var cooldownSeconds = val( retryAfter );
        if ( cooldownSeconds == 0 && len( retryAfter ) ) {
            // Try parsing as HTTP date
            try {
                var retryDate = parseDateTime( retryAfter );
                cooldownSeconds = dateDiff( "s", now(), retryDate );
            } catch ( any e ) {
                cooldownSeconds = 60; // Default 1 minute
            }
        } else if ( cooldownSeconds == 0 ) {
            cooldownSeconds = 60; // Default if no header
        }

        var cooldownUntil = dateAdd( "s", cooldownSeconds, now() );
        rateLimitCooldowns[ provider ] = cooldownUntil;

        // Log rate limit
        writeLog(
            text: "Rate limit hit for #provider#. Cooldown until #cooldownUntil# (#cooldownSeconds#s)",
            type: "warning",
            log: "ai-rate-limits"
        );

        // Track in metrics
        recordMetric( "ai.rate_limit_hit", {
            provider: provider,
            cooldownSeconds: cooldownSeconds,
            timestamp: now()
        });

        // Send alert
        sendSlackAlert({
            channel: "#ai-monitoring",
            message: "🚨 Rate limit hit for #provider#. Cooling down for #cooldownSeconds# seconds.",
            color: "warning"
        });

        // Switch to backup provider if available
        var backupProvider = getBackupProvider( provider );
        if ( backupProvider != "" ) {
            writeLog(
                text: "Switching to backup provider: #backupProvider#",
                type: "info"
            );

            // Modify request to use backup (implementation specific)
            interceptData.useBackupProvider = backupProvider;
        }

        // Update application-wide rate limit status
        application.aiRateLimits[ provider ] = {
            limitedUntil: cooldownUntil,
            backupProvider: backupProvider
        };
    }
}

---

16. beforeAIPipelineRun

Fired before a runnable pipeline sequence begins execution.

When: Before pipeline execution starts Frequency: Every pipeline run

Event Arguments

Argument	Type	Description
sequence	AiRunnableSequence	The sequence being executed
name	String	Sequence name
stepCount	Numeric	Number of steps in pipeline
steps	Array	Array of step information
input	Any	Initial input to pipeline
params	Struct	Parameters passed to pipeline
options	Struct	Options passed to pipeline

#### Example

```java
function beforeAIPipelineRun( event, interceptData ) {
    var sequence = interceptData.sequence;
    var stepCount = interceptData.stepCount;
    var steps = interceptData.steps;

    // Log pipeline execution start
    writeLog(
        text: "Starting pipeline: #sequence.getName()# with #stepCount# steps",
        type: "info",
        log: "ai-pipelines"
    );

    // Print pipeline structure for debugging
    for ( var step in steps ) {
        writeLog(
            text: "  Step #step.index#: #step.name# (#step.type#)",
            type: "info"
        );
    }

    // Validate pipeline configuration
    if ( stepCount == 0 ) {
        throw( "Cannot run empty pipeline" );
    }

    // Add tracking metadata
    var pipelineId = createUUID();
    interceptData.pipelineId = pipelineId;

    // Track pipeline execution
    recordPipelineStart({
        pipelineId: pipelineId,
        name: sequence.getName(),
        stepCount: stepCount,
        timestamp: now()
    });
}

---

17. afterAIPipelineRun

Fired after a runnable pipeline sequence completes execution.

When: After pipeline execution completes Frequency: Every pipeline run

Event Arguments

Argument	Type	Description
sequence	AiRunnableSequence	The sequence that was executed
name	String	Sequence name
stepCount	Numeric	Number of steps in pipeline
steps	Array	Array of step information
input	Any	Initial input to pipeline
result	Any	Final result from pipeline
executionTime	Numeric	Total execution time in milliseconds

#### Example

```java
function afterAIPipelineRun( event, interceptData ) {
    var sequence = interceptData.sequence;
    var result = interceptData.result;
    var executionTime = interceptData.executionTime;
    var stepCount = interceptData.stepCount;

    // Log pipeline completion
    writeLog(
        text: "Pipeline completed: #sequence.getName()# in #executionTime#ms (#stepCount# steps)",
        type: "info",
        log: "ai-pipelines"
    );

    // Track metrics
    recordMetric( "ai.pipeline.duration", {
        name: sequence.getName(),
        duration: executionTime,
        stepCount: stepCount,
        timestamp: now()
    });

    // Alert on slow pipelines
    if ( executionTime > 10000 ) {
        writeLog(
            text: "Slow pipeline execution: #sequence.getName()# took #executionTime#ms",
            type: "warning"
        );
    }

    // Calculate average time per step
    var avgStepTime = executionTime / stepCount;
    writeLog(
        text: "Average time per step: #numberFormat(avgStepTime, '0.00')#ms",
        type: "info"
    );

    // Validate results
    if ( isNull( result ) ) {
        writeLog(
            text: "Pipeline returned null result: #sequence.getName()#",
            type: "warning"
        );
    }
}

---

18. onAITokenCount

Fired when token usage information is available from the AI provider response.

When: After receiving response with usage data Frequency: Every successful API call that returns usage

Event Arguments

Argument	Type	Description
provider	IService	The provider instance
operation	String	Operation type: "chat"
model	String	Model ID used for the request
promptTokens	Numeric	Input tokens used
completionTokens	Numeric	Output tokens generated
totalTokens	Numeric	Total tokens (prompt + completion)
aiRequest	AiChatRequest	The originating chat request object
usage	Struct	Full raw usage object from provider
timestamp	DateTime	When the event was fired

#### Example

```java
class {

    property name="monthlyUsage" default={};
    property name="budgetLimits" default={
        "openai": 10000,     // $10
        "claude": 15000,     // $15
        "gemini": 20000      // $20
    };

    function onAITokenCount( event, interceptData ) {
        var provider = interceptData.provider.getProviderName();
        var model = interceptData.model;
        var totalTokens = interceptData.totalTokens;
        var promptTokens = interceptData.promptTokens;
        var completionTokens = interceptData.completionTokens;

        // Calculate cost based on provider pricing
        var cost = calculateTokenCost(
            provider,
            model,
            promptTokens,
            completionTokens
        );

        // Track monthly usage
        var currentMonth = dateFormat( now(), "yyyy-mm" );
        if ( !monthlyUsage.keyExists( currentMonth ) ) {
            monthlyUsage[ currentMonth ] = {};
        }
        if ( !monthlyUsage[ currentMonth ].keyExists( provider ) ) {
            monthlyUsage[ currentMonth ][ provider ] = {
                tokens: 0,
                cost: 0,
                requests: 0
            };
        }

        monthlyUsage[ currentMonth ][ provider ].tokens += totalTokens;
        monthlyUsage[ currentMonth ][ provider ].cost += cost;
        monthlyUsage[ currentMonth ][ provider ].requests++;

        // Log token usage
        writeLog(
            text: "Token usage: #provider# (#model#) - #totalTokens# tokens ($#numberFormat(cost, '0.0000')#)",
            type: "info",
            log: "ai-tokens"
        );

        // Store in database for analytics
        queryExecute(
            "INSERT INTO ai_token_usage (provider, model, prompt_tokens, completion_tokens, total_tokens, cost, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
            [
                provider,
                model,
                promptTokens,
                completionTokens,
                totalTokens,
                cost,
                now()
            ]
        );

        // Check budget limits
        var currentCost = monthlyUsage[ currentMonth ][ provider ].cost;
        var budgetLimit = budgetLimits.keyExists( provider ) ? budgetLimits[ provider ] : 0;

        if ( budgetLimit > 0 ) {
            var percentUsed = ( currentCost / budgetLimit ) * 100;

            // Alert at 80% budget
            if ( percentUsed >= 80 && percentUsed < 100 ) {
                sendBudgetAlert({
                    provider: provider,
                    percentUsed: percentUsed,
                    currentCost: currentCost,
                    budgetLimit: budgetLimit,
                    level: "warning"
                });
            }

            // Block at 100% budget
            if ( currentCost >= budgetLimit ) {
                writeLog(
                    text: "Budget limit exceeded for #provider#: $#currentCost# >= $#budgetLimit#",
                    type: "error"
                );

                sendBudgetAlert({
                    provider: provider,
                    percentUsed: percentUsed,
                    currentCost: currentCost,
                    budgetLimit: budgetLimit,
                    level: "critical"
                });

                // Optionally throw to prevent further usage
                // throw( "Budget limit exceeded for provider: #provider#" );
            }
        }

        // Track cost per user
        var user = interceptData.aiRequest.getMetadata().userId ?: "anonymous";
        trackUserCost( user, provider, cost, totalTokens );
    }

    private function calculateTokenCost( provider, model, promptTokens, completionTokens ) {
        // Pricing per 1M tokens (as of 2024)
        var pricing = {
            "openai": {
                "gpt-4": { prompt: 30.00, completion: 60.00 },
                "gpt-4-turbo": { prompt: 10.00, completion: 30.00 },
                "gpt-3.5-turbo": { prompt: 0.50, completion: 1.50 }
            },
            "claude": {
                "claude-3-opus": { prompt: 15.00, completion: 75.00 },
                "claude-3-sonnet": { prompt: 3.00, completion: 15.00 }
            },
            "gemini": {
                "gemini-pro": { prompt: 0.50, completion: 1.50 }
            }
        };

        // Get pricing for model
        var modelPricing = {};
        if ( pricing.keyExists( provider ) ) {
            for ( var key in pricing[ provider ] ) {
                if ( findNoCase( key, model ) ) {
                    modelPricing = pricing[ provider ][ key ];
                    break;
                }
            }
        }

        // Default pricing if not found
        if ( modelPricing.isEmpty() ) {
            modelPricing = { prompt: 1.00, completion: 2.00 };
        }

        // Calculate cost (per 1M tokens)
        var promptCost = ( promptTokens / 1000000 ) * modelPricing.prompt;
        var completionCost = ( completionTokens / 1000000 ) * modelPricing.completion;

        return promptCost + completionCost;
    }
}

---

Multi-Tenant Usage Tracking (v2.1.0+)

Track AI usage per tenant for billing and cost allocation. Works with aiChat(), aiChatAsync(), aiChatStream(), and AI Agent runnables.

// Set tenant context in AI chat requests
result = aiChat(
    messages: "Analyze this data",
    options: {
        tenantId: "customer_acme",
        usageMetadata: {
            costCenter: "engineering",
            projectId: "proj-2024-ml",
            userId: "[e-mail]",
            department: "R&D"
        }
    }
)

// Set tenant context in AI agents
agent = aiAgent(
    name: "Assistant",
    memory: aiMemory( "window" )
)

result = agent.run(
    input: "Help me with this task",
    options: {
        tenantId: "customer_acme",
        usageMetadata: {
            costCenter: "support",
            ticketId: "TICK-12345",
            priority: "high"
        }
    }
)

// Set tenant context in model runnables
model = aiModel( provider: "openai" )

result = model.run(
    input: "Generate a report",
    params: { temperature: 0.7 },
    options: {
        tenantId: "org_finance",
        usageMetadata: {
            department: "accounting",
            reportType: "quarterly"
        }
    }
)

Interceptor for Multi-Tenant Billing:

class {

    property name="billingService" inject="BillingService";

    function onAITokenCount( event, interceptData ) {
        // Extract tenant context
        var tenantId = interceptData.tenantId ?: "unknown";
        var usageMetadata = interceptData.usageMetadata ?: {};

        // Provider and model info
        var provider = interceptData.provider.getProviderName();
        var model = interceptData.model;

        // Token usage
        var totalTokens = interceptData.totalTokens;
        var promptTokens = interceptData.promptTokens;
        var completionTokens = interceptData.completionTokens;

        // Calculate cost
        var cost = calculateCost(
            provider: provider,
            model: model,
            promptTokens: promptTokens,
            completionTokens: completionTokens
        );

        // Store usage for tenant billing
        billingService.recordUsage({
            tenantId: tenantId,
            provider: provider,
            model: model,
            operation: interceptData.operation,
            totalTokens: totalTokens,
            promptTokens: promptTokens,
            completionTokens: completionTokens,
            estimatedCost: cost,
            timestamp: interceptData.timestamp,
            metadata: usageMetadata
        });

        // Check tenant quota
        var tenantQuota = billingService.getTenantQuota( tenantId );
        var currentUsage = billingService.getCurrentMonthUsage( tenantId );

        if ( currentUsage.cost + cost > tenantQuota.limit ) {
            // Send alert
            emailService.send(
                to: tenantQuota.alertEmail,
                subject: "AI Usage Quota Alert: #tenantId#",
                body: "Current usage: $#currentUsage.cost# + $#cost# exceeds limit: $#tenantQuota.limit#"
            );

            // Optionally block further usage
            if ( tenantQuota.hardLimit ) {
                throw(
                    type: "QuotaExceeded",
                    message: "Tenant #tenantId# has exceeded their AI usage quota"
                );
            }
        }

        // Log for analytics
        writeLog(
            type: "info",
            file: "ai-usage",
            text: "Tenant=#tenantId#, Provider=#provider#, Model=#model#, Tokens=#totalTokens#, Cost=$#numberFormat(cost,'0.0000')#, Metadata=#serializeJSON(usageMetadata)#"
        );
    }
}

Multi-Provider Tracking Example:

// Track usage across different providers
class TenantUsageTracker {

    property name="usageDB" inject="UsageDatabase";

    function onAITokenCount( event, interceptData ) {
        var tenantId = interceptData.tenantId;

        // Skip if no tenant context
        if ( isNull( tenantId ) || tenantId == "" ) return;

        var usageRecord = {
            tenantId: tenantId,
            provider: interceptData.provider.getProviderName(),
            model: interceptData.model,
            operation: interceptData.operation,
            tokens: {
                prompt: interceptData.promptTokens,
                completion: interceptData.completionTokens,
                total: interceptData.totalTokens
            },
            cost: calculateProviderCost( interceptData ),
            timestamp: interceptData.timestamp,
            metadata: interceptData.usageMetadata ?: {},
            providerOptions: interceptData.providerOptions ?: {}
        };

        // Store in database
        usageDB.insertUsage( usageRecord );

        // Update real-time metrics
        metricsService.increment( "ai.usage.#tenantId#.tokens", usageRecord.tokens.total );
        metricsService.increment( "ai.usage.#tenantId#.requests", 1 );
        metricsService.gauge( "ai.usage.#tenantId#.cost", usageRecord.cost );

        // Track by cost center if provided
        if ( structKeyExists( usageRecord.metadata, "costCenter" ) ) {
            var costCenter = usageRecord.metadata.costCenter;
            metricsService.increment(
                "ai.usage.#tenantId#.#costCenter#.cost",
                usageRecord.cost
            );
        }
    }

    private function calculateProviderCost( data ) {
        // Provider-specific pricing (per 1M tokens)
        var pricing = {
            "openai": {
                "gpt-4o": { prompt: 2.50, completion: 10.00 },
                "gpt-4o-mini": { prompt: 0.150, completion: 0.600 }
            },
            "bedrock": {
                "claude-3-sonnet": { prompt: 3.00, completion: 15.00 },
                "claude-3-haiku": { prompt: 0.25, completion: 1.25 }
            },
            "ollama": {
                // Free for local models
                "*": { prompt: 0, completion: 0 }
            },
            "deepseek": {
                "deepseek-chat": { prompt: 0.14, completion: 0.28 }
            }
        };

        var provider = data.provider.getProviderName();
        var model = data.model;

        // Get pricing for this provider/model
        var modelPricing = { prompt: 0, completion: 0 };

        if ( structKeyExists( pricing, provider ) ) {
            // Try exact model match
            if ( structKeyExists( pricing[ provider ], model ) ) {
                modelPricing = pricing[ provider ][ model ];
            } else {
                // Try wildcard match
                for ( var pattern in pricing[ provider ] ) {
                    if ( pattern == "*" || findNoCase( pattern, model ) ) {
                        modelPricing = pricing[ provider ][ pattern ];
                        break;
                    }
                }
            }
        }

        // Calculate cost
        var promptCost = ( data.promptTokens / 1000000 ) * modelPricing.prompt;
        var completionCost = ( data.completionTokens / 1000000 ) * modelPricing.completion;

        return promptCost + completionCost;
    }
}

Usage Metadata Examples:

// Example 1: Department-level tracking
aiChat(
    messages: "Generate report",
    options: {
        tenantId: "company_xyz",
        usageMetadata: {
            department: "marketing",
            costCenter: "CC-4501",
            campaign: "spring-2026"
        }
    }
)

// Example 2: Project-based tracking
aiChat(
    messages: "Analyze customer data",
    options: {
        tenantId: "client_acme",
        usageMetadata: {
            projectId: "proj-analytics-2026",
            projectName: "Customer Insights",
            billableHours: true,
            clientPO: "PO-12345"
        }
    }
)

// Example 3: User-level tracking
aiChat(
    messages: "Help me with code",
    options: {
        tenantId: "org_developers",
        usageMetadata: {
            userId: "[e-mail]",
            team: "backend",
            feature: "api-optimization"
        }
    }
)

// Example 4: Geographic tracking
aiChat(
    messages: "Translate content",
    options: {
        tenantId: "saas_customer_456",
        usageMetadata: {
            region: "us-west",
            datacenter: "pdx-1",
            customerTier: "enterprise"
        }
    }
)

Benefits of Multi-Tenant Tracking:

• ✅ Accurate Billing: Attribute AI costs to specific tenants/customers

• ✅ Cost Allocation: Track usage by department, project, or cost center

• ✅ Quota Management: Enforce per-tenant usage limits

• ✅ Analytics: Understand which tenants/projects use AI most

• ✅ Chargeback: Generate detailed usage reports for internal billing

• ✅ Provider Agnostic: Works with all AI providers (OpenAI, Bedrock, Ollama, etc.)

---

Event Priority Reference

Events fire in this order during a typical AI chat with tools:

1. onAIMessageCreate - Message template created

2. onAIChatRequestCreate - Request object created

3. onAIModelCreate - Model wrapper created

4. onAIToolCreate - Tool(s) created (if using tools)

5. beforeAIPipelineRun - Pipeline about to start (if using pipelines)

6. beforeAIModelInvoke - Model about to be invoked

7. onAIChatRequest - HTTP request about to be sent

8. onAIRateLimitHit - If rate limit encountered

9. onAIChatResponse - HTTP response received

10. onAITokenCount - Token usage tracked

11. beforeAIToolExecute - Tool about to execute (if AI requested tool call)

12. afterAIToolExecute - Tool execution complete

13. onAIError - If any error occurred

14. afterAIModelInvoke - Model invocation complete

15. afterAIPipelineRun - Pipeline execution complete

---

19. onMCPServerCreate

Fired when a new MCP (Model Context Protocol) server instance is created.

When: MCP server instantiation via MCPServer() Frequency: Once per unique server creation

Event Arguments

Argument	Type	Description
server	MCPServer	The created server instance
name	String	Server name/identifier
description	String	Server description
version	String	Server version

#### Example

```java
function onMCPServerCreate( event, interceptData ) {
    var server = interceptData.server;
    var name = interceptData.name;

    // Log server creation
    writeLog(
        text: "MCP Server created: #name# (v#interceptData.version#)",
        type: "info"
    );

    // Apply default configuration
    server.setCors( "*" );

    // Track server registry
    trackMCPServer( name, {
        createdAt: now(),
        description: interceptData.description
    });
}

---

20. onMCPServerRemove

Fired when an MCP server instance is being removed from the registry.

When: Before server removal via MCPServer::removeInstance() Frequency: Once per server removal

Event Arguments

Argument	Type	Description
name	String	Name of the server being removed

#### Example

```java
function onMCPServerRemove( event, interceptData ) {
    var serverName = interceptData.name;

    // Clean up server resources
    cleanupServerResources( serverName );

    // Log removal
    writeLog(
        text: "MCP Server removed: #serverName#",
        type: "info"
    );

    // Notify connected clients
    notifyClientsOfServerShutdown( serverName );
}

---

21. onMCPRequest

Fired before processing an incoming MCP request (JSON-RPC 2.0).

When: After CORS handling, before request processing Frequency: Every MCP request

Event Arguments

Argument	Type	Description
server	MCPServer	The target server instance
requestData	Struct	Request metadata (method, body, urlParams)
serverName	String	Server identifier

#### Example

```java
function onMCPRequest( event, interceptData ) {
    var server = interceptData.server;
    var requestData = interceptData.requestData;
    var serverName = interceptData.serverName;

    // Authentication for MCP requests
    if ( !isAuthorized( requestData ) ) {
        throw(
            type: "MCPAuthError",
            message: "Unauthorized MCP request"
        );
    }

    // Rate limiting
    if ( exceedsRateLimit( serverName ) ) {
        throw(
            type: "RateLimitExceeded",
            message: "Too many MCP requests"
        );
    }

    // Log request
    logMCPRequest({
        server: serverName,
        method: requestData.method,
        timestamp: now()
    });
}

---

22. onMCPResponse

Fired after processing an MCP response, before returning to client.

When: After request handling, before HTTP response Frequency: Every MCP response

Event Arguments

Argument	Type	Description
server	MCPServer	The server instance
response	Struct	Response data (content, contentType, headers, statusCode)
requestData	Struct	Original request metadata
serverName	String	Server identifier

#### Example

```java
function onMCPResponse( event, interceptData ) {
    var response = interceptData.response;
    var requestData = interceptData.requestData;
    var serverName = interceptData.serverName;

    // Add custom headers
    response.headers[ "X-MCP-Server" ] = serverName;
    response.headers[ "X-Response-Time" ] = getTickCount() - requestData.startTime;

    // Log response
    logMCPResponse({
        server: serverName,
        statusCode: response.statusCode,
        contentType: response.contentType,
        timestamp: now()
    });

    // Track metrics
    if ( response.statusCode >= 400 ) {
        incrementMetric( "mcp.errors.#serverName#" );
    }
}

---

23. onMCPError

Fired when an exception occurs during MCP server operations.

When: Exception in request handling, class scanning, or other MCP operations Frequency: When errors occur

Event Arguments

Argument	Type	Description
server	MCPServer	The server instance
context	String	Where error occurred (handleRequest, scanClass, etc.)
exception	Struct	Exception object (message, detail, stackTrace, type)
method	String	Request method (context: handleRequest)
requestId	Any	Request ID (context: handleRequest)
params	Struct	Request parameters (context: handleRequest)
responseTime	Numeric	Time elapsed in ms (context: handleRequest)
errorCode	Numeric	RPC error code (context: handleRequest)
classPath	String	Class being scanned (context: scanClass)

Example

function onMCPError( event, interceptData ) {
    var exception = interceptData.exception;
    var context = interceptData.context;
    var server = interceptData.server;

    // Log detailed error
    writeLog(
        type: "error",
        file: "mcp-errors",
        text: "MCP Error in #context#: #exception.message#\nDetail: #exception.detail#"
    );

    // Context-specific handling
    if ( context == "handleRequest" ) {
        // Request-level error
        var method = interceptData.method;
        var errorCode = interceptData.errorCode;

        // Send alert for critical errors
        if ( errorCode == -32603 ) { // SERVER_ERROR
            emailService.sendAlert(
                to: "[e-mail]",
                subject: "MCP Server Error: #server.getName()#",
                body: "Method: #method#\nError: #exception.message#\nStackTrace: #exception.stackTrace#"
            );
        }

        // Track error metrics
        metrics.increment( "mcp.errors.#method#" );
        metrics.increment( "mcp.errors.code.#errorCode#" );
    } else if ( context == "scanClass" ) {
        // Class scanning error
        writeLog(
            type: "warning",
            file: "mcp-scan-errors",
            text: "Failed to scan class: #interceptData.classPath#"
        );
    }

    // Send to error tracking service
    errorTracker.captureException(
        exception: exception,
        context: {
            mcpServer: server.getName(),
            operation: context,
            serverInfo: server.getServerInfo()
        }
    );
}

---

24. onAIToolRegistryRegister

Fired when a tool is registered with the AIToolRegistry.

When: After a tool is added via aiToolRegistry().register() or scan() Frequency: Once per registered tool

Event Arguments

Argument	Type	Description
tool	ITool	The tool instance that was registered
key	string	The registry key (e.g., "search" or "search@my-module")
module	string	The module name (empty string if none)

Example

function onAIToolRegistryRegister( event, interceptData ) {
    writeLog(
        text: "Tool registered: #interceptData.key#",
        type: "info"
    );
}

---

25. onAIToolRegistryUnregister

Fired when a tool is removed from the AIToolRegistry.

When: After a tool is removed via aiToolRegistry().unregister() or unregisterByModule() Frequency: Once per removed tool

Event Arguments

Argument	Type	Description
key	string	The registry key of the removed tool
module	string	The module name extracted from the key

Example

function onAIToolRegistryUnregister( event, interceptData ) {
    writeLog(
        text: "Tool unregistered: #interceptData.key#",
        type: "info"
    );
}

---

💡 Common Use Cases

1. Request Logging and Monitoring

function onAIChatRequest( event, interceptData ) {
    var logData = {
        timestamp: now(),
        provider: interceptData.provider.getProviderName(),
        messages: interceptData.aiRequest.getMessages(),
        params: interceptData.aiRequest.getParams(),
        user: getAuthenticatedUser()
    };

    // Log to database
    queryExecute(
        "INSERT INTO ai_request_log (data, created_at) VALUES (:data, :timestamp)",
        { data: serializeJSON( logData ), timestamp: now() }
    );
}

2. Cost Tracking and Budgeting

class {

    function onAIChatResponse( event, interceptData ) {
        if ( !interceptData.response.keyExists( "usage" ) ) return;

        var usage = interceptData.response.usage;
        var provider = interceptData.provider.getProviderName();

        // Calculate cost based on provider pricing
        var cost = calculateCost( provider, usage );

        // Track against user/org budget
        var user = getAuthenticatedUser();
        var currentUsage = getUserUsage( user );

        updateUserUsage( user, cost );

        // Alert if approaching limit
        if ( currentUsage + cost >= getUserBudget( user ) * 0.9 ) {
            sendBudgetAlert( user );
        }

        // Block if over budget
        if ( currentUsage + cost > getUserBudget( user ) ) {
            throw( "Budget exceeded for user: #user#" );
        }
    }

    private function calculateCost( provider, usage ) {
        // Pricing per 1K tokens (example rates)
        var pricing = {
            openai: {
                prompt: 0.03,
                completion: 0.06
            },
            claude: {
                prompt: 0.015,
                completion: 0.075
            }
        };

        var rates = pricing[ provider ] ?: { prompt: 0.01, completion: 0.01 };

        return (
            ( usage.prompt_tokens / 1000 ) * rates.prompt +
            ( usage.completion_tokens / 1000 ) * rates.completion
        );
    }
}

3. Response Caching

class {

    function onAIChatRequest( event, interceptData ) {
        var request = interceptData.aiRequest;
        var cacheKey = generateCacheKey( request );

        // Check cache
        var cached = cacheGet( cacheKey );
        if ( !isNull( cached ) ) {
            // Return cached response and skip actual API call
            interceptData.useCached = true;
            interceptData.cachedResponse = cached;

            writeLog(
                text: "Using cached AI response",
                type: "info"
            );
        }
    }

    function onAIChatResponse( event, interceptData ) {
        // Don't cache if we used cached response
        if ( interceptData.keyExists( "useCached" ) ) return;

        var request = interceptData.aiRequest;
        var response = interceptData.response;
        var cacheKey = generateCacheKey( request );

        // Cache for 1 hour
        cachePut(
            cacheKey,
            response,
            createTimeSpan( 0, 1, 0, 0 )
        );
    }

    private function generateCacheKey( request ) {
        var key = {
            messages: request.getMessages(),
            params: request.getParams()
        };
        return hash( serializeJSON( key ) );
    }
}

4. Content Filtering and Moderation

function onAIChatRequest( event, interceptData ) {
    var request = interceptData.aiRequest;
    var messages = request.getMessages();

    // Check for prohibited content
    for ( var msg in messages ) {
        if ( containsProhibitedContent( msg.content ) ) {
            throw(
                type: "ContentViolation",
                message: "Request contains prohibited content"
            );
        }
    }
}

function onAIChatResponse( event, interceptData ) {
    var response = interceptData.response;

    // Filter response content
    if ( response.keyExists( "choices" ) ) {
        for ( var choice in response.choices ) {
            if ( choice.keyExists( "message" ) ) {
                choice.message.content = filterContent(
                    choice.message.content
                );
            }
        }
    }
}

private function containsProhibitedContent( text ) {
    var prohibitedPatterns = [
        "pattern1",
        "pattern2"
    ];

    for ( var pattern in prohibitedPatterns ) {
        if ( findNoCase( pattern, text ) ) {
            return true;
        }
    }

    return false;
}

private function filterContent( text ) {
    // Replace sensitive information
    text = reReplace( text, "\b\d{3}-\d{2}-\d{4}\b", "[SSN]", "all" );
    text = reReplace( text, "\b\d{16}\b", "[CREDIT_CARD]", "all" );
    return text;
}

5. Multi-Provider Fallback

class {

    property name="failedProviders" default={};

    function onAIChatRequest( event, interceptData ) {
        var provider = interceptData.provider.getProviderName();

        // Check if provider is in cooldown
        if ( failedProviders.keyExists( provider ) ) {
            var cooldownEnd = failedProviders[ provider ];
            if ( now() < cooldownEnd ) {
                // Switch to backup provider
                var backup = getBackupProvider( provider );
                writeLog(
                    text: "Switching from #provider# to #backup# (cooldown)",
                    type: "warning"
                );
                // Recreate request with backup provider
                throw(
                    type: "ProviderCooldown",
                    message: "Provider in cooldown, use backup"
                );
            } else {
                // Cooldown expired, remove from list
                structDelete( failedProviders, provider );
            }
        }
    }

    function onAIChatResponse( event, interceptData ) {
        var response = interceptData.response;
        var provider = interceptData.provider.getProviderName();

        // Check for rate limiting
        if ( response.keyExists( "error" ) &&
             response.error.type == "rate_limit_exceeded" ) {

            // Put provider in 5-minute cooldown
            failedProviders[ provider ] = dateAdd( "n", 5, now() );

            writeLog(
                text: "Provider #provider# rate limited, cooldown until #failedProviders[provider]#",
                type: "warning"
            );
        }
    }

    private function getBackupProvider( provider ) {
        var backups = {
            "openai": "claude",
            "claude": "gemini",
            "gemini": "openai"
        };
        return backups[ provider ] ?: "openai";
    }
}

6. A/B Testing Different Models

class {

    function onAIChatRequest( event, interceptData ) {
        var request = interceptData.aiRequest;
        var user = getAuthenticatedUser();

        // Assign users to test groups
        var testGroup = hash( user ).left( 1 ) < "8" ? "A" : "B";

        if ( testGroup == "A" ) {
            // Group A: GPT-4
            request.setParam( "model", "gpt-4" );
        } else {
            // Group B: Claude
            request.setParam( "model", "claude-3-opus" );
        }

        // Track which group
        request.setMetadata({
            testGroup: testGroup,
            experimentId: "model_comparison_2024"
        });
    }

    function onAIChatResponse( event, interceptData ) {
        var request = interceptData.aiRequest;
        var response = interceptData.response;
        var metadata = request.getMetadata();

        // Log results for analysis
        logExperiment({
            experimentId: metadata.experimentId,
            testGroup: metadata.testGroup,
            model: request.getParams().model,
            tokensUsed: response.usage?.total_tokens ?: 0,
            timestamp: now()
        });
    }
}

7. Adding Safety Guardrails

class {

    function beforeAIModelInvoke( event, interceptData ) {
        var request = interceptData.request;

        // Add safety system message
        var messages = request.getMessages();
        var safetyMessage = {
            role: "system",
            content: "You must not provide information about: illegal activities, violence, harmful content, or personal data. If asked, politely decline and explain why."
        };

        // Prepend safety instructions
        arrayPrepend( messages, safetyMessage );
        request.setMessages( messages );
    }

    function afterAIModelInvoke( event, interceptData ) {
        var results = interceptData.results;

        // Check response for policy violations
        if ( isStruct( results ) && results.keyExists( "choices" ) ) {
            for ( var choice in results.choices ) {
                if ( violatesSafetyPolicy( choice.message.content ) ) {
                    // Override response
                    choice.message.content = "I cannot provide that information as it may violate safety policies.";

                    // Log violation
                    logSafetyViolation({
                        request: interceptData.request,
                        originalResponse: choice.message.content,
                        timestamp: now()
                    });
                }
            }
        }
    }

    private function violatesSafetyPolicy( content ) {
        // Implement your safety checks
        var violations = [
            "personal information",
            "illegal activity",
            "violence"
        ];

        for ( var violation in violations ) {
            if ( findNoCase( violation, content ) ) {
                return true;
            }
        }

        return false;
    }
}

---

✅ Best Practices

1. Keep Event Handlers Lightweight

Event handlers are called frequently. Keep processing minimal:

// ❌ Bad: Heavy processing
function onAIChatRequest( event, interceptData ) {
    // This runs complex queries and blocks
    var history = getAllUserAIHistory( getUser() );
    analyzeHistoryForPatterns( history );
}

// ✅ Good: Lightweight, async if needed
function onAIChatRequest( event, interceptData ) {
    // Quick validation only
    validateRequest( interceptData.aiRequest );

    // Heavy work done async
    runAsync( function() {
        trackRequest( interceptData.aiRequest );
    });
}

2. Handle Errors Gracefully

Don't let interceptor errors break AI operations:

function onAIChatResponse( event, interceptData ) {
    try {
        // Your processing
        processResponse( interceptData.response );
    } catch ( any e ) {
        // Log but don't throw
        writeLog(
            text: "Error in interceptor: #e.message#",
            type: "error"
        );
        // Continue without breaking the flow
    }
}

3. Document Side Effects

Make it clear what your interceptors modify:

/**
 * AI Request Interceptor
 *
 * Modifies:
 * - Adds X-Request-ID header
 * - Overrides temperature to 0.7 if not set
 * - Logs request to database
 *
 * Does NOT modify:
 * - Message content
 * - Model selection
 */
function onAIChatRequest( event, interceptData ) {
    // Implementation
}

4. Use Naming Conventions

// Prefix interceptor classes with purpose
AIMonitoringInterceptor.bx
AISecurityInterceptor.bx
AICostTrackingInterceptor.bx
AIContentFilterInterceptor.bx

5. Order Matters

Interceptors execute in registration order. Be mindful:

interceptors = [
    { class: "SecurityInterceptor" },      // Run first: validate
    { class: "CostTrackingInterceptor" },  // Then: track costs
    { class: "LoggingInterceptor" }        // Finally: log
];

6. Test Interceptors Independently

Write unit tests for your interceptor logic:

// tests/interceptors/AIMonitorTest.bx
class extends="testbox.system.BaseSpec" {

    function run() {
        describe( "AIMonitor Interceptor", function() {

            it( "should log requests", function() {
                var monitor = new interceptors.AIMonitor();
                var interceptData = {
                    aiRequest: mockRequest(),
                    provider: mockProvider()
                };

                monitor.onAIChatRequest( {}, interceptData );

                // Verify logging occurred
                expect( getLogEntries() ).toHaveLength( 1 );
            });
        });
    }
}

7. Make Interceptors Configurable

class {

    property name="enabled" default=true;
    property name="logLevel" default="info";
    property name="destinations" default=["console","file"];

    function configure() {
        // Read from settings
        variables.enabled = getSetting( "monitoring.enabled" );
        variables.logLevel = getSetting( "monitoring.logLevel" );
    }

    function onAIChatRequest( event, interceptData ) {
        if ( !variables.enabled ) return;

        // Use configuration
        log( interceptData, variables.logLevel );
    }
}

---

📚 Examples

Complete Monitoring Solution

// interceptors/AICompleteMonitor.bx
class {

    property name="sessionId";

    function configure() {
        variables.sessionId = createUUID();
    }

    function onAIMessageCreate( event, interceptData ) {
        trackEvent( "message_created", {
            messageCount: arrayLen( interceptData.message.getMessages() )
        });
    }

    function onAIModelCreate( event, interceptData ) {
        trackEvent( "model_created", {
            provider: interceptData.service.getProviderName()
        });
    }

    function beforeAIModelInvoke( event, interceptData ) {
        interceptData.request.setMetadata({
            startTime: getTickCount(),
            sessionId: variables.sessionId
        });
    }

    function onAIChatRequest( event, interceptData ) {
        var request = interceptData.aiRequest;
        var metadata = request.getMetadata();

        trackEvent( "request_sent", {
            provider: interceptData.provider.getProviderName(),
            messageCount: arrayLen( request.getMessages() ),
            sessionId: metadata.sessionId
        });
    }

    function onAIChatResponse( event, interceptData ) {
        var request = interceptData.aiRequest;
        var response = interceptData.response;

        trackEvent( "response_received", {
            provider: interceptData.provider.getProviderName(),
            tokensUsed: response.usage?.total_tokens ?: 0,
            sessionId: request.getMetadata().sessionId
        });
    }

    function afterAIModelInvoke( event, interceptData ) {
        var request = interceptData.request;
        var metadata = request.getMetadata();
        var duration = getTickCount() - metadata.startTime;

        trackEvent( "invocation_complete", {
            duration: duration,
            sessionId: metadata.sessionId
        });
    }

    private function trackEvent( eventName, data ) {
        // Your analytics implementation
        analyticsService.track( eventName, data );
    }
}

Security and Compliance

// interceptors/AISecurityCompliance.bx
class {

    function onAIChatRequest( event, interceptData ) {
        var request = interceptData.aiRequest;
        var user = getAuthenticatedUser();

        // Validate user has permission
        if ( !hasPermission( user, "ai.use" ) ) {
            throw(
                type: "SecurityViolation",
                message: "User not authorized for AI operations"
            );
        }

        // Redact sensitive data
        var messages = request.getMessages();
        for ( var msg in messages ) {
            msg.content = redactSensitiveData( msg.content );
        }
        request.setMessages( messages );

        // Add audit trail
        request.setMetadata({
            userId: user.getId(),
            ipAddress: getClientIP(),
            timestamp: now()
        });
    }

    function onAIChatResponse( event, interceptData ) {
        // Log for compliance
        auditLog({
            userId: interceptData.aiRequest.getMetadata().userId,
            action: "ai_query",
            provider: interceptData.provider.getProviderName(),
            timestamp: now(),
            tokensUsed: interceptData.response.usage?.total_tokens ?: 0
        });
    }

    private function redactSensitiveData( text ) {
        // Email addresses
        text = reReplace( text, "\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", "[EMAIL]", "all" );
        // Phone numbers
        text = reReplace( text, "\b\d{3}[-.]?\d{3}[-.]?\d{4}\b", "[PHONE]", "all" );
        // SSN
        text = reReplace( text, "\b\d{3}-\d{2}-\d{4}\b", "[SSN]", "all" );
        return text;
    }
}

---

---

🔊 Audio Events (34–39)

34. beforeAISpeech

Fired before a text-to-speech request is sent to the provider.

When: Before aiSpeak() dispatches the HTTP request

Event Arguments

Argument	Type	Description
speechRequest	Struct	The full TTS request object
service	any	The AI service provider instance

Example

BoxRegisterInterceptor( "beforeAISpeech", function( event ) {
    println( "TTS request: provider=#event.service.getName()# chars=#event.speechRequest.text.len()#" )
})

---

35. afterAISpeech

Fired after a text-to-speech response has been received from the provider.

When: After aiSpeak() receives and wraps the audio binary in AiSpeechResponse

Event Arguments

Argument	Type	Description
speechRequest	Struct	The original TTS request object
service	any	The AI service provider instance
result	AiSpeechResponse	The response object with audio data

Example

BoxRegisterInterceptor( "afterAISpeech", function( event ) {
    var sizeKB = event.result.getSize() / 1024
    println( "TTS complete: #event.service.getName()# — #numberFormat( sizeKB, '0.0' )# KB" )
})

---

36. beforeAITranscription

Fired before a speech-to-text request is sent to the provider.

When: Before aiTranscribe() dispatches the HTTP request

Event Arguments

Argument	Type	Description
transcriptionRequest	Struct	The full STT request object
service	any	The AI service provider instance

Example

BoxRegisterInterceptor( "beforeAITranscription", function( event ) {
    println( "STT request: provider=#event.service.getName()#" )
})

---

37. afterAITranscription

Fired after a speech-to-text response has been received from the provider.

When: After aiTranscribe() receives the transcription response

Event Arguments

Argument	Type	Description
transcriptionRequest	Struct	The original STT request object
service	any	The AI service provider instance
result	AiTranscriptionResponse	The transcription response object

Example

BoxRegisterInterceptor( "afterAITranscription", function( event ) {
    println( "Transcribed: #event.result.getWordCount()# words via #event.service.getName()#" )
})

---

38. beforeAITranslation

Fired before an audio translation request is sent to the provider.

When: Before aiTranslate() dispatches the HTTP request

Event Arguments

Argument	Type	Description
transcriptionRequest	Struct	The full translation request object
service	any	The AI service provider instance

Example

BoxRegisterInterceptor( "beforeAITranslation", function( event ) {
    println( "Audio translation request: #event.service.getName()#" )
})

---

39. afterAITranslation

Fired after an audio translation response has been received from the provider.

When: After aiTranslate() receives the English text response

Event Arguments

Argument	Type	Description
transcriptionRequest	Struct	The original translation request object
service	any	The AI service provider instance
result	AiTranscriptionResponse	The response with English text

Example

BoxRegisterInterceptor( "afterAITranslation", function( event ) {
    println( "Translated: #event.result.getWordCount()# English words" )
})

---

🧠 Memory Events (40–41)

40. onHybridMemoryAdd

Fired when a message is added to a HybridMemory instance. Use this to audit, transform, or track messages as they enter hybrid memory.

When: Inside HybridMemory.add() after the message has been processed

Event Arguments

Argument	Type	Description
memory	HybridMemory	The memory instance receiving the message
message	AiMessage	The message being added

Example

BoxRegisterInterceptor( "onHybridMemoryAdd", function( event ) {
    println( "Hybrid memory received: role=#event.message.getRole()# chars=#event.message.getContent().len()#" )
})

---

41. onVectorSearch

Fired whenever a semantic search runs against a vector memory store. Use this for observability, caching query results, or logging retrieval quality.

When: After IVectorMemory.getRelevant() or findSimilar() returns results

Event Arguments

Argument	Type	Description
memory	IVectorMemory	The vector memory instance that was searched
query	String	The search query string
limit	Numeric	Maximum number of results requested
results	Array	Array of retrieved documents/messages

Example

BoxRegisterInterceptor( "onVectorSearch", function( event ) {
    println( "Vector search: query='#event.query#' found=#event.results.len()# limit=#event.limit#" )
})

---

42. beforeAIImageGeneration

Fired before an image generation request is sent to the provider.

When: Before aiImage() sends the HTTP request

Event Arguments

Argument	Type	Description
imageRequest	AiImageRequest	The image generation request object
service	IAiImageService	The image service instance

Example

BoxRegisterInterceptor( "beforeAIImageGeneration", function( event ) {
    println( "Generating image: prompt='#event.imageRequest.prompt#'" )
})

---

43. afterAIImageGeneration

Fired after an image generation response is received from the provider.

When: After aiImage() receives the response

Event Arguments

Argument	Type	Description
imageRequest	AiImageRequest	The image generation request object
service	IAiImageService	The image service instance
result	AiImageResponse	The generated image response

Example

BoxRegisterInterceptor( "afterAIImageGeneration", function( event ) {
    println( "Generated #event.result.getCount()# image(s) via #event.service.getName()#" )
})

---

44. onAIImageRequest

Fired when an image request object is created.

When: During aiImage() request construction

Event Arguments

Argument	Type	Description
imageRequest	AiImageRequest	The image request object

Example

BoxRegisterInterceptor( "onAIImageRequest", function( event ) {
    // Modify request parameters
    event.imageRequest.setSize( "1792x1024" )
})

---

45. onAIImageResponse

Fired after an image response is received from the provider.

When: After the provider returns generated images

Event Arguments

Argument	Type	Description
response	AiImageResponse	The image response
rawResponse	struct	Raw provider response
provider	string	Provider name

Example

BoxRegisterInterceptor( "onAIImageResponse", function( event ) {
    logMetric( "ai.image.generated", {
        provider: event.provider,
        count: event.result.getCount()
    })
})

---

46. onAIAgentRegistryRegister

Fired when an agent is registered in the global agent registry.

When: On aiAgentRegistry().register() or aiAgent( register: true )

Event Arguments

Argument	Type	Description
agent	AiAgent	The registered agent
key	string	Registry key (e.g., agentName@module)
module	string	Module namespace

Example

BoxRegisterInterceptor( "onAIAgentRegistryRegister", function( event ) {
    println( "Agent registered: #event.key#" )
})

---

47. onAIAgentRegistryUnregister

Fired when an agent is removed from the global agent registry.

When: On aiAgentRegistry().unregister() or unregisterByModule()

Event Arguments

Argument	Type	Description
key	string	Registry key
module	string	Module namespace

Example

BoxRegisterInterceptor( "onAIAgentRegistryUnregister", function( event ) {
    println( "Agent unregistered: #event.key#" )
})

---

48. onMCPServerPause

Fired when an MCP server is paused.

When: On MCPServer.pause()

Event Arguments

Argument	Type	Description
server	MCPServer	The MCP server instance
name	string	Server name

Example

BoxRegisterInterceptor( "onMCPServerPause", function( event ) {
    println( "MCP server paused: #event.name#" )
})

---

49. onMCPServerResume

Fired when an MCP server is resumed.

When: On MCPServer.resume()

Event Arguments

Argument	Type	Description
server	MCPServer	The MCP server instance
name	string	Server name

Example

BoxRegisterInterceptor( "onMCPServerResume", function( event ) {
    println( "MCP server resumed: #event.name#" )
})

---

50. onMCPClientRequest

Fired before an MCP client sends an HTTP request.

When: Before every MCP client HTTP call

Event Arguments

Argument	Type	Description
client	MCPClient	The MCP client instance
baseURL	string	Server base URL
operation	string	Operation type (tool, resource, prompt, discovery)
name	string	Tool/resource/prompt name
requestBody	struct	Request payload

Example

BoxRegisterInterceptor( "onMCPClientRequest", function( event ) {
    println( "MCP client #event.operation#: #event.name#" )
})

---

51. onMCPClientResponse

Fired after an MCP client receives a successful HTTP response.

When: On successful MCP client HTTP response

Event Arguments

Argument	Type	Description
client	MCPClient	The MCP client instance
baseURL	string	Server base URL
operation	string	Operation type
name	string	Tool/resource/prompt name
response	MCPResponse	The response object
executionTime	numeric	Request duration in ms
statusCode	numeric	HTTP status code

Example

BoxRegisterInterceptor( "onMCPClientResponse", function( event ) {
    println( "MCP response: #event.operation#/#event.name# in #event.executionTime#ms" )
})

---

52. onMCPClientError

Fired when an MCP client encounters an HTTP error or network exception.

When: On HTTP errors (bad status / JSON-RPC error) or network exceptions

Event Arguments

Argument	Type	Description
client	MCPClient	The MCP client instance
baseURL	string	Server base URL
operation	string	Operation type
name	string	Tool/resource/prompt name
error	string	Error message
statusCode	numeric	HTTP status code (if available)
executionTime	numeric	Request duration in ms
exception	any	Exception object (if from catch block)

Example

BoxRegisterInterceptor( "onMCPClientError", function( event ) {
    logError( "MCP client error: #event.operation#/#event.name# — #event.error#" )
})

---

🌐 Web Search Events (53–57)

53. beforeAIWebSearch

Fired before a web search provider executes a query.

When: At the start of BaseSearch.search(), before the provider runs

Argument	Type	Description
provider	ISearchProvider	The search provider instance
query	String	The search query
options	Struct	Search options (maxResults, etc.)

54. afterAIWebSearch

Fired after a web search returns results successfully.

Argument	Type	Description
provider	ISearchProvider	The search provider instance
query	String	The search query
options	Struct	Search options
results	Array	Normalized result array
cached	Boolean	Whether the results came from cache

BoxRegisterInterceptor( "afterAIWebSearch", function( event ) {
    println( "Search '#event.query#' returned #event.results.len()# results" )
})

55. onAIWebSearchRequest

Fired immediately before the provider's outbound HTTP request.

Argument	Type	Description
provider	ISearchProvider	The search provider instance
url	String	The request URL
method	String	HTTP method
headers	Struct	Request headers

56. onAIWebSearchResponse

Fired after the provider's HTTP response is received.

Argument	Type	Description
provider	ISearchProvider	The search provider instance
url	String	The request URL
statusCode	Numeric	HTTP status code
response	Struct	The raw HTTP response

57. onAIWebSearchError

Fired when a web search throws.

Argument	Type	Description
provider	ISearchProvider	The search provider instance
query	String	The search query
options	Struct	Search options
error	Exception	The thrown exception

---

🧠 Memory Summarization Event (58)

58. onAIMemorySummarize

Fired after a memory instance successfully compresses its history into an AI-generated summary. Available on every conversation memory type, not just SummaryMemory.

When: Inside BaseMemory.summarize(), after the summary is stored

Argument	Type	Description
memory	IAiMemory	The memory instance that was summarized
key	String	The memory key
type	String	The memory type name
userId	String	Tenant user id, if set
conversationId	String	Conversation id, if set
messageCount	Numeric	Messages remaining after compression
summaryLength	Numeric	Character length of the generated summary
keepRecent	Numeric	How many recent messages were kept verbatim
summarizedCount	Numeric	How many messages were folded into the summary

BoxRegisterInterceptor( "onAIMemorySummarize", function( event ) {
    println( "Compressed #event.summarizedCount# messages for #event.userId# into #event.summaryLength# chars" )
})

---

🔌 Gateway Events (59–61)

Gateways present human-in-the-loop interactions on a platform (CLI, HTTP, or an external module). See the Security Guide and Middleware.

59. onGatewayCreate

Fired whenever aiGateway() resolves or instantiates a gateway — for core gateways, registry-provided gateways, and direct class paths alike.

Argument	Type	Description
gateway	IGateway	The configured gateway instance

BoxRegisterInterceptor( "onGatewayCreate", function( event ) {
    println( "Gateway ready: #event.gateway.getName()#" )
})

60. onGatewayRegistryRegister

Fired when a gateway is registered into aiGatewayRegistry() — typically by an external gateway module at load time.

Argument	Type	Description
gateway	IGateway	The gateway being registered
key	String	Registry key (name or name@module)
module	String	Owning module name, if any

61. onGatewayRegistryUnregister

Fired when a gateway is removed from the registry.

Argument	Type	Description
key	String	Registry key removed
module	String	Module extracted from the key

---

🔐 Decision Store Event (62)

62. onAiDecisionStoreCreate

Fired when aiDecisionStore() creates a store for durable human-approval grants (approve_always / approve_session).

Argument	Type	Description
storeType	String	Requested type (cache, jdbc, file, or a class path)
storeClass	String	Resolved class path
storeConfig	Struct	Configuration passed to the store

BoxRegisterInterceptor( "onAiDecisionStoreCreate", function( event ) {
    println( "Decision store: #event.storeType# -> #event.storeClass#" )
})

---

🎮 Gateway Session & Run Control Events (63–69)

63. onGatewaySessionCreate

Fired when aiGatewaySession() constructs a GatewaySession.

Argument	Type	Description
session	GatewaySession	The constructed session (not yet started)

BoxRegisterInterceptor( "onGatewaySessionCreate", function( event ) {
    println( "Gateway session created for agent: #event.session.getAgent().getName()#" )
})

64. onGatewayConnect

Fired from a gateway's start(), only on a real not-running → running transition (never on a redundant call while already running). A gateway extending BaseGateway gets this tracking automatically.

Argument	Type	Description
gateway	IGateway	The gateway that just started

65. onGatewayDisconnect

Fired from a gateway's stop(), only on a real running → not-running transition.

Argument	Type	Description
gateway	IGateway	The gateway that just stopped

66. onGatewayMessageReceived

Fired from a gateway's parseInbound(), once per parsed inbound message.

Argument	Type	Description
gateway	IGateway	The gateway that received the message
message	any	The parsed message payload
threadId	String	Thread the message belongs to
userId	String	Sender's user id, if known
conversationId	String	Conversation id, if known

BoxRegisterInterceptor( "onGatewayMessageReceived", function( event ) {
    log.info( "Message on thread #event.threadId# from user #event.userId#" )
})

67. onGatewayMessageSent

Fired from a gateway's deliver(), once per outbound delivery.

Argument	Type	Description
gateway	IGateway	The gateway that sent the message
event	any	The outbound event/payload
context	Struct	Delivery context
result	GatewayDeliveryResult	The delivery result
threadId	String	Thread the message belongs to

68. onAIAgentRunCancel

Fired when agent.cancelRun( threadId ) actually affects a run currently in flight — never on the no-op case (no run in flight for that thread).

Argument	Type	Description
agent	AiAgent	The agent whose run was cancelled
threadId	String	The thread the cancelled run belongs to
reason	String	The cancellation reason passed to cancelRun()

69. onAIAgentRunSteer

Fired when agent.steerRun( threadId, input ) actually affects a run currently in flight — never on the no-op case.

Argument	Type	Description
agent	AiAgent	The agent whose run was steered
threadId	String	The thread the steered run belongs to
input	any	The message spliced into the live turn

BoxRegisterInterceptor( "onAIAgentRunSteer", function( event ) {
    println( "Steered run on thread #event.threadId#" )
})

---

Next Steps

Now that you understand the event system, you can:

• Monitor: Track AI usage and performance

• Secure: Add authentication and content filtering

• Optimize: Implement caching and cost controls

• Extend: Build custom behaviors without modifying core code

Related Documentation

• Pipeline Overview - Understanding AI pipelines

• Service-Level Chatting - Direct service control

Additional Resources

• BoxLang Interceptor Documentation: Learn more about the interceptor system

• Event-Driven Architecture: Best practices for event handling

• Security Guidelines: Protecting AI operations

---

Copyright © 2023-2025 Ortus Solutions, Corp