AI Routing

ColdBox provides first-class AI routing via toAi() and toMCP(), enabling automatic registration of AI inference and Model Context Protocol endpoints.

circle-exclamation

ColdBox 8.1 introduces two powerful routing terminators for building AI-powered HTTP APIs:

  • toAi() — Registers four standard AI inference endpoints (invoke, stream, batch, info) for any IAiRunnable object

  • toMCP() — Registers a Model Context Protocol (MCP) server endpoint handled by MCPRequestProcessor

Both terminators behave like the resources() terminator: a single declaration expands to multiple concrete routes and all shared route modifiers (.as(), .withModule(), .withDomain(), etc.) are inherited by every generated sub-route.


toAi()

Overview

route( "/api/assistant" ).toAi( "models.AssistantAgent" );

A single toAi() call registers four routes automatically:

HTTP Verb
Pattern
Handler Action
Purpose

POST

/api/assistant/invoke

invoke

Synchronous single-turn inference

POST

/api/assistant/stream

stream

Server-Sent Events (SSE) streaming output

POST

/api/assistant/batch

batch

Batch / multi-turn inference

GET

/api/assistant/info

info

Metadata — model name, capabilities, etc.

Arguments

route( pattern ).toAi( target, [name] )
Argument
Type
Description

target

string or object

A WireBox mapping string or a live object instance that implements IAiRunnable

name

string

Optional base name for the generated routes. Defaults to the route pattern.

Basic Example

This produces the following routes:

Modifier Inheritance

All standard route modifiers are inherited by every sub-route generated by toAi():

Invoke Endpoint

The invoke action handles a standard synchronous request/response cycle.

Request body (JSON):

Response (JSON):

Stream Endpoint

The stream action returns a Server-Sent Events (SSE) stream. The client should set Accept: text/event-stream.

Request body (JSON):

SSE Response:

Batch Endpoint

The batch action accepts an array of prompts and returns an array of responses in the same order.

Request body (JSON):

Response (JSON):

Info Endpoint

The info action (GET) returns metadata about the AI runnable — model name, version, available capabilities, etc.

Response (JSON):

IAiRunnable Interface

Your agent class must implement coldbox.system.web.routing.IAiRunnable (or satisfy its duck-typed interface on BoxLang). The expected methods are:


toMCP()

Overview

toMCP() registers a Model Context Protocolarrow-up-right server endpoint. MCP is an open standard that allows AI models to interact with external tools, data sources, and services via a uniform API.

Arguments

Argument
Type
Description

name

string

Optional route name. Defaults to the route pattern.

The actual MCP server to execute is resolved from the URL pattern. You can define either a static name or use the :mcpServer placeholder to select the server dynamically from the URL.

Static Server

Use the :mcpServer placeholder in your pattern to allow the URL to identify which MCP server to invoke:

Modifier Inheritance

Like toAi(), all modifiers are inherited:

MCP Server Registration

MCP servers are registered via WireBox or the ColdBox configuration. Refer to the BoxLang AI documentationarrow-up-right and the Agentic ColdBoxarrow-up-right guide for details on building and registering MCP servers.


Using Both Together

Last updated

Was this helpful?