From coldbox-agent-skills
Use this skill when integrating AI capabilities into a ColdBox application using the BoxLang AI library (bx-ai module) -- including simple chat, streaming, pipelines, agents, RAG with vector memory, document loading, tool calling, and injecting the AI service into handlers or models.
How this skill is triggered — by the user, by Claude, or both
Slash command
/coldbox-agent-skills:ai-integrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill when adding AI features to a ColdBox/BoxLang application: chatbots, content generation, code assistance, semantic search (RAG), autonomous agents, or AI-enriched handlers and services.
Use this skill when adding AI features to a ColdBox/BoxLang application: chatbots, content generation, code assistance, semantic search (RAG), autonomous agents, or AI-enriched handlers and services.
Full SDK docs: https://ai.ortusbooks.com/
box install bx-ai
moduleSettings = {
"bx-ai" : {
// Default provider: openai, claude, gemini, ollama, etc.
defaultProvider : "openai",
providers : {
openai : {
apiKey : getSystemSetting( "OPENAI_API_KEY", "" ),
model : "gpt-4o"
},
claude : {
apiKey : getSystemSetting( "ANTHROPIC_API_KEY", "" ),
model : "claude-opus-4-5"
},
ollama : {
baseUrl : "http://localhost:11434",
model : "llama3"
}
}
}
};
All BIFs are available globally in BoxLang after installing bx-ai:
| BIF | Purpose | Returns |
|---|---|---|
aiChat( prompt, options ) | One-shot chat | String |
aiChatAsync( prompt, options ) | Non-blocking chat | Future |
aiChatRequest() | Build structured request | AiChatRequest |
aiChatStream( prompt, callback ) | Real-time streaming | void |
aiService() | Get AI service instance | Service |
aiAgent() | Create autonomous agent | AiAgent |
aiMessage() | Build message pipeline | AiMessage |
aiModel() | Create model runnable | AiModel |
aiTransform() | Create data transformer | Transformer |
aiTool() | Define callable function | Tool |
aiMemory() | Create conversation/vector memory | Memory |
aiDocuments() | Load documents for RAG | Array/Loader |
aiChunk() | Split text into chunks | Array |
aiEmbed() | Generate vector embeddings | Array/Struct |
aiPopulate() | Populate struct/class from AI JSON | Any |
aiTokens() | Estimate token count | Numeric |
// Basic Q&A
var answer = aiChat( "What is ColdBox?" )
// With options
var answer = aiChat(
"Write a product description for: #rc.productName#",
{
temperature : 0.7,
model : "gpt-4o",
provider : "openai"
}
)
// Return structured JSON
var user = aiChat(
"Create a user profile for Alice, age 30, developer",
{ returnFormat: "json" }
)
// user.name, user.age, user.email etc.
// Stream to a closure (useful for server-sent events)
aiChatStream(
"Tell me about BoxLang in detail",
( chunk ) => {
var token = chunk.choices?.first()?.delta?.content ?: ""
print( token )
}
)
// Non-blocking — returns a Future
var future = aiChatAsync( "Summarize this article: #rc.articleText#" )
// Do other work...
var summary = future.get( 30, "seconds" )
// handlers/ContentHandler.bx
class ContentHandler extends coldbox.system.EventHandler {
@inject("AIService@bx-ai")
property name="aiService";
function summarize( event, rc, prc ) {
prc.summary = aiChat(
"Summarize the following in 3 bullet points: #rc.content#",
{ temperature: 0.3 }
)
event.setView( "content/summary" )
}
// Streaming via SSE
function streamSummary( event, rc, prc ) {
event.renderData( type: "plain", data: "" )
aiChatStream(
"Summarize: #rc.content#",
( chunk ) => {
var token = chunk.choices?.first()?.delta?.content ?: ""
// write to output buffer
writeOutput( token )
flushOutput()
}
)
}
}
Pipelines chain message templates, models, and transformers for reusable, parameterized AI workflows:
// Build a reusable pipeline
var pipeline = aiMessage()
.system( "You are a helpful ColdBox expert. Answer concisely." )
.user( "Explain ${topic} with a short code example in BoxLang." )
.toDefaultModel()
.transform( ( result ) => result.content )
// Execute the pipeline with parameters
var answer = pipeline.run( { topic: "interceptors" } )
// Reuse with different params
var answer2 = pipeline.run( { topic: "scheduled tasks" } )
Allow AI to call your application functions to get real-time data:
// Define a tool
var getProductTool = aiTool(
name : "get_product",
description : "Get product information by SKU",
parameters : {
sku : { type: "string", description: "Product SKU code" }
},
callback : ( args ) => {
var product = productService.findBySku( args.sku );
return {
name : product.getName(),
price : product.getPrice(),
inStock : product.isInStock()
};
}
)
// Use the tool in a chat request
var response = aiChat(
"Is product SKU-1234 in stock and what is the price?",
{ tools: [ getProductTool ] }
)
// Windowed memory (last N messages) — in-memory
var memory = aiMemory( type: "windowed", size: 10 )
// Session memory — survives page refresh
var memory = aiMemory( type: "session" )
// Multi-tenant — use userId + conversationId for isolation
var memory = aiMemory(
type : "windowed",
size : 20,
userId : auth().getUser().getId(),
conversationId : rc.conversationId
)
// Use memory in chat
var response = aiChat( rc.userMessage, { memory: memory } )
// Vector memory for semantic RAG
var vectorMemory = aiMemory( type: "boxvector" ) // in-memory vector store
// or: type: "postgres", type: "chroma", type: "pinecone", etc.
// Load documents
var docs = aiDocuments( source: expandPath( "/docs/manual.md" ) )
// Also supports PDFs, HTML, URLs, CSV, SQL, directories
var docs = aiDocuments( source: "https://docs.ortussolutions.com/coldbox/" )
var docs = aiDocuments( source: expandPath( "/docs/" ) ) // directory loader
// Store in vector memory
var vectorMemory = aiMemory( type: "boxvector" )
vectorMemory.addDocuments( docs )
// Query with context-aware chat
function askDocs( event, rc, prc ) {
prc.answer = aiChat(
rc.question,
{ memory: vectorMemory }
)
event.renderData( data: { answer: prc.answer } )
}
Autonomous agents with memory, tools, and multi-turn conversation:
// Create an agent
var assistant = aiAgent()
.name( "ColdBox Support Assistant" )
.instructions( "You help developers build ColdBox applications. Use the provided tools to look up docs and examples." )
.memory( aiMemory( type: "windowed", size: 20 ) )
.tools( [ searchDocsTool, getExampleTool ] )
.provider( "claude" )
// Multi-turn conversation
var response1 = assistant.chat( "How do I create an interceptor?" )
var response2 = assistant.chat( "Can you show me a security example?" ) // remembers context
| Loader | Source |
|---|---|
| Text / Markdown | .txt, .md files |
| HTML | .html files or URLs |
.pdf files | |
| CSV / JSON / XML | Structured data files |
| SQL | JDBC datasource + query |
| Directory | Scan folder recursively |
| Web Crawler | Follow links on a site |
| HTTP | Any URL with auth/headers |
| Feed | RSS/Atom feeds |
// Multi-source ingestion into one vector store
var memory = aiMemory( type: "boxvector" )
memory
.addDocuments( aiDocuments( source: expandPath( "/docs/" ) ) )
.addDocuments( aiDocuments( source: "https://docs.example.com" ) )
// Generate embeddings for semantic similarity
var embeddings = aiEmbed([
"ColdBox is an HMVC framework",
"WireBox is a dependency injection framework",
"TestBox is a testing framework"
])
// Single text
var embedding = aiEmbed( "How does WireBox injection work?" )
bx-ai via CommandBox: box install bx-ai — this is a BoxLang module, not a CFML module.aiChat, aiAgent, etc.) are available globally in BoxLang after installation.aiChatAsync() for background processing; never block the HTTP request with long AI calls.aiMemory( type: "session" ) for per-user chat history tied to the HTTP session.aiMemory( type: "windowed" ) with explicit userId + conversationId for multi-tenant isolation.postgres, pinecone, qdrant) over boxvector (in-memory only).npx claudepluginhub coldbox/skillsProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.