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 34 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
• aiWebSearch() - Provider-agnostic web search with normalized results
• aiWebSearchAsync() - Asynchronous web search returning Future

🤖 Agents & Models

Create autonomous agents and model runnables.

• aiAgent() - Create AI agents with tools, memory, and reasoning
• aiAgentRegistry() - Access the global agent registry singleton
• aiModel() - Create AI model runnables for pipelines
• aiService() - Get AI service provider instances

🖼️ Image Generation

Generate images from text prompts.

• aiImage() - Generate images with direct or fluent builder APIs

💾 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

🧑‍⚖️ Human-in-the-Loop & Gateways

Present approvals to a human and route them through a platform.

• aiGateway() - Resolve a gateway (CLI, HTTP, or an external module) by name
• aiGatewayRegistry() - Registry external gateway modules register into
• aiGatewaySession() - Wire an agent to one or more gateways for inbound message handling
• aiDecisionStore() - Durable store for approve_always/approve_session grants

🛡️ Security

Defend against prompt injection and data leakage.

• aiFence() - Fence untrusted content so the model treats it as data, not instructions

🎯 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
aiDecisionStore()	HITL	Durable approval-grant store
aiDocuments()	Documents	Load documents for RAG
aiEmbed()	Documents	Generate embeddings
aiFence()	Security	Fence untrusted content
aiGateway()	Gateways	Resolve a gateway by name
aiGlobalSkills()	Skills	List globally loaded skills
aiImage()	Image	Generate images
aiMemory()	Memory	Create memory instances
aiMessage()	Messages	Build message structures
aiModel()	Models	Create model runnables
aiParallel()	Pipelines	Run branches in parallel
aiAgentRegistry()	Agents	Global agent registry
aiPopulate()	Utilities	Populate classes from JSON
aiService()	Services	Get service providers
aiSkill()	Skills	Create a skill definition
aiSpeak()	Audio	Text-to-speech generation
aiTokens()	Utilities	Estimate token counts
aiTool()	Tools	Create callable tools
aiToolRegistry()	Tools	Access the global tool registry
aiTranscribe()	Audio	Speech-to-text transcription
aiTransform()	Transform	Create transformers
aiTranslate()	Audio	Audio-to-English translation
aiWebSearch()	Search	Search web content
aiWebSearchAsync()	Search	Async web search
aiGatewayRegistry()	Gateways	Registry for external gateway modules
aiGatewaySession()	Gateways	Wire an agent to gateways for inbound messages
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