# AI Routing

{% hint style="warning" %}
AI Routing requires **BoxLang** and the **bx-ai** module. It is not available on CFML engines.
{% endhint %}

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

```javascript
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

```javascript
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

```javascript
// config/Router.bx
function configure(){

    // Register a single AI agent — four endpoints created automatically
    route( "/api/chat" ).toAi( "models.ChatAgent" );

}
```

This produces the following routes:

```
POST /api/chat/invoke  → models.ChatAgent::invoke()
POST /api/chat/stream  → models.ChatAgent::stream()
POST /api/chat/batch   → models.ChatAgent::batch()
GET  /api/chat/info    → models.ChatAgent::info()
```

### Modifier Inheritance

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

```javascript
route( "/api/chat" )
    .withModule( "myModule" )
    .withDomain( "api.myapp.com" )
    .toAi( "models.ChatAgent" );
```

### Invoke Endpoint

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

**Request body (JSON):**

```json
{
  "prompt": "Summarize this document",
  "context": { "documentId": 42 }
}
```

**Response (JSON):**

```json
{
  "response": "This document covers...",
  "model": "gpt-4o",
  "tokens": 128
}
```

### Stream Endpoint

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

**Request body (JSON):**

```json
{
  "prompt": "Write a haiku about coding"
}
```

**SSE Response:**

```
data: {"token": "Code"}
data: {"token": " flows"}
data: {"token": " like water"}
data: [DONE]
```

### Batch Endpoint

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

**Request body (JSON):**

```json
{
  "prompts": [
    "Translate: Hello",
    "Translate: Goodbye"
  ]
}
```

**Response (JSON):**

```json
{
  "responses": [
    { "response": "Hola", "model": "gpt-4o" },
    { "response": "Adiós", "model": "gpt-4o" }
  ]
}
```

### Info Endpoint

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

**Response (JSON):**

```json
{
  "model":    "gpt-4o",
  "provider": "openai",
  "capabilities": ["invoke", "stream", "batch"]
}
```

### IAiRunnable Interface

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

```javascript
// models/ChatAgent.bx
class implements="coldbox.system.web.routing.IAiRunnable" {

    function invoke( event, rc, prc ){}
    function stream( event, rc, prc ){}
    function batch( event, rc, prc ){}
    function info( event, rc, prc ){}

}
```

***

## toMCP()

### Overview

`toMCP()` registers a [Model Context Protocol](https://modelcontextprotocol.io/) server endpoint. MCP is an open standard that allows AI models to interact with external tools, data sources, and services via a uniform API.

```javascript
route( "/mcp/:mcpServer" ).toMCP();
```

### Arguments

```javascript
route( pattern ).toMCP( [name] )
```

| 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

```javascript
// Always routes to the "myServer" MCP server
route( "/mcp/assistant" ).toMCP( "myServer" );
```

### Dynamic Server (Recommended)

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

```javascript
// /mcp/codeReviewer  →  MCPRequestProcessor dispatching to "codeReviewer"
// /mcp/dataAnalyst   →  MCPRequestProcessor dispatching to "dataAnalyst"
route( "/mcp/:mcpServer" ).toMCP();
```

### Modifier Inheritance

Like `toAi()`, all modifiers are inherited:

```javascript
route( "/mcp/:mcpServer" )
    .withSSL()
    .withDomain( "mcp.myapp.com" )
    .toMCP();
```

### MCP Server Registration

MCP servers are registered via WireBox or the ColdBox configuration. Refer to the [BoxLang AI documentation](https://ai.ortusbooks.com/) and the [Agentic ColdBox](https://github.com/ortus-docs/coldbox-docs/blob/v8.x/the-basics/digging-deeper/ai/agentic-coldbox.md) guide for details on building and registering MCP servers.

***

## Using Both Together

```javascript
// config/Router.bx
function configure(){

    // AI inference for a specific assistant
    route( "/api/v1/chat" )
        .withSSL()
        .toAi( "models.ChatAgent" );

    // MCP server hub — any registered MCP server accessible via URL
    route( "/mcp/:mcpServer" )
        .withSSL()
        .toMCP();

}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coldbox.ortusbooks.com/the-basics/routing/routing-dsl/ai-routing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.