Built-In Functions Reference

Reference documentation for built-in functions in BoxLang AI module

Complete reference documentation for all BoxLang AI built-in functions (BIFs). These functions provide the primary interface for AI operations in BoxLang.

📚 Overview

The BoxLang AI module provides 18 built-in functions organized into functional categories:

🗨️ Chat & Conversation

Core functions for AI chat interactions.

• aiChat() - Synchronous AI chat with simple interface

• aiChatAsync() - Asynchronous chat returning Future

• aiChatStream() - Streaming chat with real-time callbacks

• aiChatRequest() - Create reusable request objects

🤖 Agents & Models

Create autonomous agents and model runnables.

• aiAgent() - Create AI agents with tools, memory, and reasoning

• aiModel() - Create AI model runnables for pipelines

• aiService() - Get AI service provider instances

💾 Memory & Context

Manage conversation history and knowledge bases.

• aiMemory() - Create memory instances (conversation, vector, cache, etc.)

📄 Documents & RAG

Load and process documents for RAG workflows.

• aiDocuments() - Load documents with fluent API

• aiChunk() - Chunk text into segments

• aiEmbed() - Generate vector embeddings

🔄 Transformation & Pipelines

Transform data in AI pipelines.

• aiMessage() - Build message structures with fluent API

• aiTransform() - Create transformation runnables

• aiPopulate() - Populate classes from AI responses

🔧 Tools & Utilities

Extend AI capabilities and estimate costs.

• aiTool() - Create callable tools for agents

• aiTokens() - Estimate token counts and costs

🔌 MCP (Model Context Protocol)

Connect AI to external tools and data sources.

• MCP() - Create MCP client for consuming servers

• MCPServer() - Create MCP server for exposing tools

🎯 Quick Reference

Common Usage Patterns

Simple Chat

response = aiChat( "What is BoxLang?" );

Agent with Tools

agent = aiAgent(
    name: "Assistant",
    tools: [ myTool ],
    memory: aiMemory( "window" )
);
response = agent.run( "Help me with this task" );

RAG (Retrieval Augmented Generation)

// Load documents into vector memory
vectorMemory = aiMemory( "chroma" );
aiDocuments( "/docs" ).toMemory( vectorMemory );

// Query with context
agent = aiAgent( memory: vectorMemory );
response = agent.run( "What does the documentation say about X?" );

Streaming Responses

aiChatStream(
    "Tell me a long story",
    ( chunk ) => { write( chunk ); flush; }
);

Structured Output

class Person {
    property name="firstName";
    property name="age" type="numeric";
}

person = aiChat(
    "Extract: John Doe, age 30",
    {},
    { returnFormat: new Person() }
);

📊 Function Categories by Use Case

For Simple AI Calls

Start with these for basic AI interactions:

• aiChat() - Simplest sync chat

• aiMessage() - Build complex messages

• aiService() - Get provider instance

For Long-Running Operations

Use async/streaming for better UX:

• aiChatAsync() - Non-blocking requests

• aiChatStream() - Real-time responses

For Autonomous Behavior

Let AI reason and use tools:

• aiAgent() - Autonomous agents

• aiTool() - Create callable functions

• aiMemory() - Maintain context

For Knowledge Bases (RAG)

Build AI that knows your data:

• aiDocuments() - Load documents

• aiMemory() - Vector storage

• aiEmbed() - Generate embeddings

• aiChunk() - Split documents

For Pipelines

Chain AI operations:

• aiModel() - Model runnables

• aiTransform() - Data transformation

• aiMessage() - Fluent message building

For External Integration

Connect AI to external systems:

• MCP() - Consume MCP servers

• MCPServer() - Expose tools via MCP

• aiTool() - Wrap any function

🔑 Key Concepts

Return Formats

All chat functions support multiple return formats:

• "single": Just the content string (default for aiChat())

• "all": Array of all messages

• "raw": Complete API response with metadata

• "json": Parsed JSON object

• "xml": Parsed XML document

• Class/Struct: Structured output (populate target)

Provider Selection

Three ways to specify AI provider:

1. Default: Uses module configuration

2. Parameter: aiChat( msg, {}, { provider: "claude" } )

3. Environment: Auto-detects <PROVIDER>_API_KEY variables

Memory Types

Different memory for different needs:

• Window: Recent conversation (short-term)

• Vector: Semantic search (RAG, knowledge)

• Cache: Distributed storage (CacheBox)

• File: Simple persistence

• JDBC: Database-backed

• Session: User session scope

Fluent APIs

Many functions return objects with chainable methods:

docs = aiDocuments( "/path" )
    .recursive()
    .extensions( ["md"] )
    .chunkSize( 1000 )
    .filter( doc => doc.metadata.size < 100000 )
    .load();

🎓 Learning Path

Beginner

1. Start with aiChat() for simple requests

2. Learn aiMessage() for structured conversations

3. Try aiChatStream() for real-time responses

Intermediate

1. Create aiAgent() with basic tools

2. Use aiMemory() for conversation context

3. Implement aiTool() for custom functions

Advanced

1. Build RAG systems with aiDocuments() and vector memory

2. Use aiChatAsync() for concurrent requests

3. Create MCP servers with MCPServer()

4. Build complex pipelines with aiModel() and aiTransform()

🔍 Function Index

Function	Category	Description
aiAgent()	Agents	Create autonomous AI agents
aiChat()	Chat	Synchronous AI chat
aiChatAsync()	Chat	Asynchronous AI chat
aiChatRequest()	Chat	Create request objects
aiChatStream()	Chat	Streaming AI chat
aiChunk()	Documents	Chunk text into segments
aiDocuments()	Documents	Load documents for RAG
aiEmbed()	Documents	Generate embeddings
aiMemory()	Memory	Create memory instances
aiMessage()	Messages	Build message structures
aiModel()	Models	Create model runnables
aiPopulate()	Utilities	Populate classes from JSON
aiService()	Services	Get service providers
aiTokens()	Utilities	Estimate token counts
aiTool()	Tools	Create callable tools
aiTransform()	Transform	Create transformers
MCP()	MCP	Create MCP client
MCPServer()	MCP	Create MCP server

📖 Additional Resources

• Getting Started Guide - Introduction to BoxLang AI

• Agents Documentation - Deep dive into agents

• Memory Systems - Memory types and usage

• RAG Guide - Build knowledge-based AI

• Transformers - Data transformation

• Examples - Working code examples

💡 Tips

• Start simple: Begin with aiChat() before moving to agents

• Use appropriate memory: Window for chat, vector for knowledge

• Clear tool descriptions: Help AI choose correct tools

• Handle errors: Wrap AI calls in try/catch blocks

• Monitor costs: Use aiTokens() to estimate usage

• Test locally: Use Ollama for free local testing

• Stream long responses: Better UX with aiChatStream()

• Async for parallel: Use aiChatAsync() for multiple concurrent requests