# Built-In Functions Reference

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()`**](/advanced/reference/built-in-functions/aichat.md) - Synchronous AI chat with simple interface
* [**`aiChatAsync()`**](/advanced/reference/built-in-functions/aichatasync.md) - Asynchronous chat returning Future
* [**`aiChatStream()`**](/advanced/reference/built-in-functions/aichatstream.md) - Streaming chat with real-time callbacks
* [**`aiChatRequest()`**](/advanced/reference/built-in-functions/aichatrequest.md) - Create reusable request objects

### 🤖 Agents & Models

Create autonomous agents and model runnables.

* [**`aiAgent()`**](/advanced/reference/built-in-functions/aiagent.md) - Create AI agents with tools, memory, and reasoning
* [**`aiModel()`**](/advanced/reference/built-in-functions/aimodel.md) - Create AI model runnables for pipelines
* [**`aiService()`**](/advanced/reference/built-in-functions/aiservice.md) - Get AI service provider instances

### 💾 Memory & Context

Manage conversation history and knowledge bases.

* [**`aiMemory()`**](/advanced/reference/built-in-functions/aimemory.md) - Create memory instances (conversation, vector, cache, etc.)

### 📄 Documents & RAG

Load and process documents for RAG workflows.

* [**`aiDocuments()`**](/advanced/reference/built-in-functions/aidocuments.md) - Load documents with fluent API
* [**`aiChunk()`**](/advanced/reference/built-in-functions/aichunk.md) - Chunk text into segments
* [**`aiEmbed()`**](/advanced/reference/built-in-functions/aiembed.md) - Generate vector embeddings

### 🔄 Transformation & Pipelines

Transform data in AI pipelines.

* [**`aiMessage()`**](/advanced/reference/built-in-functions/aimessage.md) - Build message structures with fluent API
* [**`aiTransform()`**](/advanced/reference/built-in-functions/aitransform.md) - Create transformation runnables
* [**`aiPopulate()`**](/advanced/reference/built-in-functions/aipopulate.md) - Populate classes from AI responses

### 🔧 Tools & Utilities

Extend AI capabilities and estimate costs.

* [**`aiTool()`**](/advanced/reference/built-in-functions/aitool.md) - Create callable tools for agents
* [**`aiTokens()`**](/advanced/reference/built-in-functions/aitokens.md) - Estimate token counts and costs

### 🔌 MCP (Model Context Protocol)

Connect AI to external tools and data sources.

* [**`MCP()`**](/advanced/reference/built-in-functions/mcp.md) - Create MCP client for consuming servers
* [**`MCPServer()`**](/advanced/reference/built-in-functions/mcpserver.md) - Create MCP server for exposing tools

## 🎯 Quick Reference

### Common Usage Patterns

#### Simple Chat

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

#### Agent with Tools

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

#### RAG (Retrieval Augmented Generation)

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

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

#### Structured Output

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

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

## 🎓 Learning Path

### Beginner

1. Start with [`aiChat()`](/advanced/reference/built-in-functions/aichat.md) for simple requests
2. Learn [`aiMessage()`](/advanced/reference/built-in-functions/aimessage.md) for structured conversations
3. Try [`aiChatStream()`](/advanced/reference/built-in-functions/aichatstream.md) for real-time responses

### Intermediate

4. Create [`aiAgent()`](/advanced/reference/built-in-functions/aiagent.md) with basic tools
5. Use [`aiMemory()`](/advanced/reference/built-in-functions/aimemory.md) for conversation context
6. Implement [`aiTool()`](/advanced/reference/built-in-functions/aitool.md) for custom functions

### Advanced

7. Build RAG systems with [`aiDocuments()`](/advanced/reference/built-in-functions/aidocuments.md) and vector memory
8. Use [`aiChatAsync()`](/advanced/reference/built-in-functions/aichatasync.md) for concurrent requests
9. Create MCP servers with [`MCPServer()`](/advanced/reference/built-in-functions/mcpserver.md)
10. Build complex pipelines with [`aiModel()`](/advanced/reference/built-in-functions/aimodel.md) and [`aiTransform()`](/advanced/reference/built-in-functions/aitransform.md)

## 🔍 Function Index

| Function                                                                     | Category  | Description                 |
| ---------------------------------------------------------------------------- | --------- | --------------------------- |
| [`aiAgent()`](/advanced/reference/built-in-functions/aiagent.md)             | Agents    | Create autonomous AI agents |
| [`aiChat()`](/advanced/reference/built-in-functions/aichat.md)               | Chat      | Synchronous AI chat         |
| [`aiChatAsync()`](/advanced/reference/built-in-functions/aichatasync.md)     | Chat      | Asynchronous AI chat        |
| [`aiChatRequest()`](/advanced/reference/built-in-functions/aichatrequest.md) | Chat      | Create request objects      |
| [`aiChatStream()`](/advanced/reference/built-in-functions/aichatstream.md)   | Chat      | Streaming AI chat           |
| [`aiChunk()`](/advanced/reference/built-in-functions/aichunk.md)             | Documents | Chunk text into segments    |
| [`aiDocuments()`](/advanced/reference/built-in-functions/aidocuments.md)     | Documents | Load documents for RAG      |
| [`aiEmbed()`](/advanced/reference/built-in-functions/aiembed.md)             | Documents | Generate embeddings         |
| [`aiMemory()`](/advanced/reference/built-in-functions/aimemory.md)           | Memory    | Create memory instances     |
| [`aiMessage()`](/advanced/reference/built-in-functions/aimessage.md)         | Messages  | Build message structures    |
| [`aiModel()`](/advanced/reference/built-in-functions/aimodel.md)             | Models    | Create model runnables      |
| [`aiPopulate()`](/advanced/reference/built-in-functions/aipopulate.md)       | Utilities | Populate classes from JSON  |
| [`aiService()`](/advanced/reference/built-in-functions/aiservice.md)         | Services  | Get service providers       |
| [`aiTokens()`](/advanced/reference/built-in-functions/aitokens.md)           | Utilities | Estimate token counts       |
| [`aiTool()`](/advanced/reference/built-in-functions/aitool.md)               | Tools     | Create callable tools       |
| [`aiTransform()`](/advanced/reference/built-in-functions/aitransform.md)     | Transform | Create transformers         |
| [`MCP()`](/advanced/reference/built-in-functions/mcp.md)                     | MCP       | Create MCP client           |
| [`MCPServer()`](/advanced/reference/built-in-functions/mcpserver.md)         | MCP       | Create MCP server           |

## 📖 Additional Resources

* [**Getting Started Guide**](/getting-started/getting-started.md) - Introduction to BoxLang AI
* [**Agents Documentation**](/main-components/agents.md) - Deep dive into agents
* [**Memory Systems**](/main-components/memory.md) - Memory types and usage
* [**RAG Guide**](/rag/rag.md) - Build knowledge-based AI
* [**Transformers**](/main-components/transformers.md) - Data transformation
* [**Examples**](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/examples/README.md) - 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


---

# 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://ai.ortusbooks.com/advanced/reference/built-in-functions.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.