# Chatting

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. Please note that chatting can only get you so far. For complex workflows, state management, and agentic behavior, check out the [Main Components](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/main-components/README.md) section for pipelines and agents.

## 📖 Overview

The `aiChat(), aiChatAsync(), and aiChatStream()` BIFs 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](/main-components/chatting/basic-chatting.md)

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](/main-components/chatting/advanced-chatting.md)

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](/main-components/chatting/service-chatting.md)

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](/main-components/chatting/structured-output.md)

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

```java
result = aiChat( "What is BoxLang?" )
```

### With Specific Provider + Model

```java
result = aiChat(
    messages: "Explain quantum computing",
    { model: "claude-3-5-sonnet-20241022" }
    { provider: "claude" }
)
```

### Streaming Response

```java
aiChatStream(
    messages: "Write a poem about code",
    callback: ( chunk ) => print( chunk ),
    params: { model: "gpt-4o" },
    options: { provider: "openai" }
)
```

### Function Calling

```java
weatherTool = aiTool(
    name: "getWeather",
    description: "Get current weather for a city",
    callable: ( required location ) => {
        // Call your weather API here and return results
        return callWeatherAPI( location )
    }
)

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

### Structured Output

```java
result = aiChat(
    messages: "Extract: John is 30, works as developer in NYC",
    options: {
        returnFormat: {
            name: "string",
            age: "numeric",
            job: "string",
            location: "string"
        }
    }
);
println( result.name ) // "John"
```

***

## Choosing Your Path

**"I just need simple AI responses"** → [Basic Chatting](/main-components/chatting/basic-chatting.md)

**"I want real-time streaming or tool calling"** → [Advanced Chatting](/main-components/chatting/advanced-chatting.md)

**"I need reusable service configurations"** → [Service-Level Chatting](/main-components/chatting/service-chatting.md)

**"I want to build complex workflows"** → See [Main Components](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/main-components/README.md) 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](/main-components/chatting/basic-chatting.md)
2. **Add advanced features** - [Advanced Chatting](/main-components/chatting/advanced-chatting.md)
3. **Optimize with services** - [Service-Level Chatting](/main-components/chatting/service-chatting.md)
4. **Scale with pipelines** - [Main Components](https://github.com/ortus-boxlang/bx-ai-docs/blob/v2.x/main-components/main-components/README.md)


---

# 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/main-components/chatting.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.