Chatting

Learn how to use the productive BoxLang AI chatting features for building conversational AI applications with ease.

Simple, powerful AI interactions using Built-in Functions (BIFs). This section covers everything from basic chat to advanced features like streaming, tools, and structured output.

📖 Overview

The aiChat() BIF provides the fastest way to interact with AI providers. Whether you need a quick answer or a sophisticated multi-turn conversation, these patterns cover your use cases without the overhead of pipelines or agents.

Perfect for:

• Quick AI queries and one-off interactions

• Prototyping and experimentation

• Simple conversational interfaces

• Direct provider control

---

📚 Guides

💬 Basic Chatting

Master the fundamentals of AI interactions.

What you'll learn:

• Making your first AI call with aiChat()

• Understanding message roles (system, user, assistant)

• Managing conversation history

• Choosing and configuring providers

• Working with different return formats

Start here if: You're new to BoxLang AI or need simple question-answer interactions.

---

🎯 Advanced Chatting

Unlock powerful features for sophisticated applications.

What you'll learn:

• Streaming responses - Real-time token-by-token output

• Function calling (tools) - Let AI call your functions and APIs

• Structured output - Extract data into classes, structs, or arrays

• Multimodal content - Process images, audio, video, and documents

• JSON mode - Force valid JSON responses

• Temperature & creativity - Control response randomness

Start here if: You need real-time updates, tool integration, or data extraction.

---

⚙️ Service-Level Chatting

Direct service instance management for reusability and control.

What you'll learn:

• Creating reusable service instances

• Configuring providers with custom settings

• Managing multiple configurations

• Invoking services directly vs using BIFs

• When to use services vs aiChat()

Start here if: You need fine-grained control, custom configurations, or want to reuse service instances.

---

📦 Structured Output

Extract type-safe, validated data from AI responses.

What you'll learn:

• Using BoxLang classes for typed responses

• Struct templates for quick prototyping

• Extracting arrays of data

• Multiple schemas in one request

• Manual population with aiPopulate()

Start here if: You need reliable data extraction, type safety, or want to eliminate manual parsing.

---

Quick Examples

Simple Chat

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

With Specific Provider

result = aiChat(
    provider: "claude",
    message: "Explain quantum computing",
    model: "claude-3-5-sonnet-20241022"
);

Streaming Response

aiChat(
    message: "Write a poem about code",
    stream: true,
    onChunk: ( chunk ) => print( chunk )
);

Function Calling

weatherTool = aiTool()
    .setFunction( getWeather )
    .setDescription( "Get weather for a location" );

result = aiChat(
    message: "What's the weather in Boston?",
    tools: [ weatherTool ]
);

Structured Output

result = aiChat(
    message: "Extract: John is 30, works as developer in NYC",
    structured: {
        name: "string",
        age: "numeric",
        job: "string",
        location: "string"
    }
);

---

Choosing Your Path

"I just need simple AI responses" → Basic Chatting

"I want real-time streaming or tool calling" → Advanced Chatting

"I need reusable service configurations" → Service-Level Chatting

"I want to build complex workflows" → See Main Components for pipelines and agents

---

Key Concepts

Message Roles

• system - Instructions that define AI behavior

• user - Your questions or prompts

• assistant - AI's responses

Return Formats

• single (default) - Returns content string directly

• all - Returns full response struct with metadata

• raw - Returns complete API response

Provider Selection

Use the provider parameter or set OPENAI_API_KEY, CLAUDE_API_KEY, etc. in your environment.

---

Next Steps

1. Start with basics - Basic Chatting

2. Add advanced features - Advanced Chatting

3. Optimize with services - Service-Level Chatting

4. Scale with pipelines - Main Components