AI Agents

The complete guide to AI Agents in BoxLang, covering creation, memory management, tool usage, configuration, and advanced patterns.

AI Agents are autonomous entities that can reason, use tools, and maintain conversation memory. Inspired by LangChain agents but "Boxified" for simplicity and productivity, agents handle complex AI workflows by automatically managing state, context, and tool execution.

📖 Table of Contents

• What are AI Agents?

• Creating Agents

• Memory Management

• Configuration

• Return Formats

• Streaming Responses

• Pipeline Integration

• Agents with Document Loaders & RAG

• Agents with Transformers

• Advanced Patterns

  • Sub-Agents (Delegation)

  • Event Interception

• Best Practices

• Real-World Examples

🎯 What are AI Agents?

An agent is more than a simple chat interface - it's an intelligent entity that:

• Maintains Memory: Remembers conversation history across interactions

• Uses Tools: Can call functions to access data, perform calculations, or interact with systems

• Reasons and Plans: Determines when and how to use tools to accomplish tasks

• Manages State: Automatically handles message history and context

• Integrates with Pipelines: Works seamlessly in BoxLang AI pipelines

• Delegates to Sub-Agents: Can orchestrate specialized sub-agents for complex tasks

🏗️ Agent Architecture

🔄 Agent Decision Flow

🚀 Creating Agents

Basic Agent

// Simple agent with default settings
agent = aiAgent(
    name: "Assistant",
    description: "A helpful AI assistant",
    instructions: "Be concise and friendly"
)

response = agent.run( "What is BoxLang?" )
println( response )

Agent with Custom Model

// Agent with specific AI model
model = aiModel( "claude" ).configure( apiKey: "sk-..." )

agent = aiAgent(
    name: "Claude Assistant",
    model: model,
    params: { temperature: 0.7 }
)

Agent with Tools

Tools enable agents to perform real-world actions:

// Create tools
weatherTool = aiTool(
    "get_weather",
    "Get current weather for a location",
    location => {
        // Call weather API
        return getWeatherData( location )
    }
).describeLocation( "City and country, e.g. Boston, MA" )

calculatorTool = aiTool(
    "calculate",
    "Perform mathematical calculations",
    expression => evaluate( expression )
).describeExpression( "Math expression to evaluate" )

// Create agent with tools
agent = aiAgent(
    name: "TaskAgent",
    description: "An agent that can check weather and do math",
    instructions: "Use tools when needed. Be precise and helpful.",
    tools: [ weatherTool, calculatorTool ]
)

// Agent automatically uses tools when needed
response = agent.run( "What's the weather in Boston and what's 15% of 250?" )

💭 Memory Management

Agents automatically maintain conversation history:

🔄 Memory Flow

Window Memory (Default)

// Agent with conversation memory
agent = aiAgent(
    name: "ChatBot",
    description: "A conversational assistant",
    memory: aiMemory( "simple" )
)

// First interaction
agent.run( "My name is Luis" )
// Response: "Nice to meet you, Luis!"

// Second interaction - agent remembers
agent.run( "What's my name?" )
// Response: "Your name is Luis"

// Access memory messages
messages = agent.getMemoryMessages()
println( messages )  // All conversation history

// Clear memory when needed
agent.clearMemory()

Multiple Memory Systems

Agents can use multiple memory instances:

agent = aiAgent(
    name: "MultiMemoryAgent",
    memory: [
        aiMemory( "simple" ),      // Conversation history
        customMemory               // Custom memory implementation
    ]
)

// Agent stores in all memory systems
agent.run( "Remember this fact: BoxLang is awesome" )

⚙️ Configuration

Constructor-Based Configuration

Agents are configured primarily through the constructor:

agent = aiAgent(
    name: "CodeReviewer",
    description: "A code review specialist",
    instructions: "Review code for best practices, security, and performance",
    model: aiModel( "openai" ),
    tools: [ lintTool, securityTool ],
    memory: aiMemory( "simple" ),
    params: { temperature: 0.3, max_tokens: 1000 }
)

response = agent.run( "Review this function: ${codeSnippet}" )

Fluent Configuration

For runtime configuration changes, use setter methods:

agent = aiAgent(
    name: "Assistant",
    description: "Helpful assistant"
)
    .setModel( aiModel( "claude" ) )
    .addTool( searchTool )
    .addMemory( customMemory )
    .setParam( "temperature", 0.7 )

response = agent.run( "Help me with this task" )

📤 Return Formats

Agents support five return formats: single, all, json, xml, and raw.

Return Format Flow

Single (Default)

Agents default to "single" format, returning just the assistant's content as a string:

// Default behavior - returns string
content = agent.run( "Hello" )
println( content )  // "Hello! How can I help you?"

// Explicitly specify (same result)
content = agent.run( "Hello", {}, { returnFormat: "single" } )
println( content )  // "Hello! How can I help you?"

All Messages

Returns all messages including system, memory context, and response:

allMessages = agent.run( "Hello", {}, { returnFormat: "all" } )
// Returns array:
// [
//   { role: "system", content: "..." },
//   { role: "user", content: "Previous message" },
//   { role: "assistant", content: "Previous response" },
//   { role: "user", content: "Hello" },
//   { role: "assistant", content: "Hello! How can I help you?" }
// ]

Raw Response

Returns the full provider response structure:

rawResponse = agent.run( "Hello", {}, { returnFormat: "raw" } )
// Returns complete OpenAI/Claude/etc response with metadata
println( rawResponse.usage.total_tokens )  // Token count
println( rawResponse.model )                // Model used

JSON Format

jsonResponse = agent.run( "Hello", {}, { returnFormat: "json" } )
// Returns response as JSON string
println( jsonResponse )  // JSON formatted string

XML Format

xmlResponse = agent.run( "Hello", {}, { returnFormat: "xml" } )
// Returns response as XML string
println( xmlResponse )  // XML formatted string

Streaming Responses

Stream agent responses in real-time:

agent = aiAgent(
    name: "StreamAgent",
    description: "Streaming assistant"
)

// Stream with callback
agent.stream(
    onChunk: ( chunk ) => {
        // Process each chunk
        content = chunk.choices?.first()?.delta?.content ?: ""
        print( content )
    },
    input: "Write a story about BoxLang"
)

Pipeline Integration

Agents implement IAiRunnable, so they work in pipelines:

// Agent in a pipeline
pipeline = aiMessage()
    .user( "Task: ${task}" )
    .to( agent )
    .transform( r => r.toUpper() )

result = pipeline.run( { task: "Summarize AI trends in 2025" } )

Chaining Agents

// Multiple agents in sequence
researchAgent = aiAgent( name: "Researcher" )
summaryAgent = aiAgent( name: "Summarizer" )
editorAgent = aiAgent( name: "Editor" )

pipeline = aiMessage()
    .user( "Research: ${topic}" )
    .to( researchAgent )
    .transform( r => "Summarize this: ${r}" )
    .to( summaryAgent )
    .transform( r => "Edit and polish: ${r}" )
    .to( editorAgent )

result = pipeline.run( { topic: "Quantum Computing" } )

Advanced Patterns

Agent with Dynamic Tools

// Function that returns tools based on context
function getToolsForUser( userRole ) {
    if ( userRole == "admin" ) {
        return [ adminTool, userTool, reportTool ]
    }
    return [ userTool ]
}

// Create agent with dynamic tools
agent = aiAgent( name: "ContextAgent" )
    .setTools( getToolsForUser( getCurrentUserRole() ) )

Agent Introspection

Inspect agent configuration at runtime using getConfig():

// Create an agent
agent = aiAgent(
    name: "Inspector",
    description: "Analysis agent",
    instructions: "Analyze data carefully",
    model: aiModel( "openai", { temperature: 0.7 } ),
    tools: [ searchTool, calculatorTool ],
    params: { maxTokens: 2000 }
)

// Get comprehensive configuration
config = agent.getConfig()

// Access agent properties
println( config.name )          // "Inspector"
println( config.description )   // "Analysis agent"
println( config.instructions )  // "Analyze data carefully"

// Access model configuration object
println( config.model.name )         // "gpt-4o-mini"
println( config.model.provider )     // "openai"
println( config.model.toolCount )    // 2
println( config.model.params.temperature )  // 0.7

// Access memories (array of memory summaries)
config.memories.each( function( mem ) {
    println( mem.type )          // e.g., "SessionMemory"
    println( mem.messageCount )  // Number of stored messages
} )

// Access execution parameters
println( config.params.maxTokens )  // 2000
println( config.options.returnFormat )  // "single" (default)

Conditional Agent Execution

// Execute agent based on conditions
function processRequest( userInput, requiresTools ) {
    if ( requiresTools ) {
        agent = aiAgent(
            name: "ToolAgent",
            tools: [ weatherTool, calculatorTool ]
        )
    } else {
        agent = aiAgent( name: "SimpleAgent" )
    }

    return agent.run( userInput )
}

Sub-Agents

Sub-agents allow you to create specialized agents that can be delegated to by a parent agent. When you register a sub-agent, it is automatically wrapped as an internal tool that the parent agent can invoke.

Creating Agents with Sub-Agents

// Create specialized sub-agents
mathAgent = aiAgent(
    name: "MathAgent",
    description: "A mathematics expert",
    instructions: "You help with mathematical calculations and concepts"
)

codeAgent = aiAgent(
    name: "CodeAgent",
    description: "A programming expert",
    instructions: "You help with code review and writing"
)

// Create parent agent with sub-agents
mainAgent = aiAgent(
    name: "OrchestratorAgent",
    description: "Main coordinator that delegates to specialists",
    instructions: """
        Analyze each request and delegate to appropriate sub-agents:
        - MathAgent: For mathematical tasks
        - CodeAgent: For programming tasks
        Answer directly for simple queries.
    """,
    subAgents: [ mathAgent, codeAgent ]
)

// The parent agent automatically has delegation tools available
response = mainAgent.run( "Write a function to calculate factorial" )

Fluent Sub-Agent API

You can also add sub-agents using the fluent API:

// Create sub-agents
helperAgent = aiAgent( name: "HelperAgent", description: "General helper" )
specialistAgent = aiAgent( name: "SpecialistAgent", description: "Specialist" )

// Add sub-agents fluently
mainAgent = aiAgent( name: "MainAgent" )
    .addSubAgent( helperAgent )
    .addSubAgent( specialistAgent )

// Or replace all sub-agents
mainAgent.setSubAgents( [ newAgent1, newAgent2 ] )

Sub-Agent Management

// Check if a sub-agent exists
if ( mainAgent.hasSubAgent( "MathAgent" ) ) {
    println( "Math agent is available" )
}

// Get a specific sub-agent
mathAgent = mainAgent.getSubAgent( "MathAgent" )
if ( !isNull( mathAgent ) ) {
    // Use the sub-agent directly
    result = mathAgent.run( "What is 2 + 2?" )
}

// Get all sub-agents
allSubAgents = mainAgent.getSubAgents()
println( "Total sub-agents: #allSubAgents.len()#" )

Sub-Agents in Configuration

Sub-agent information is included in getConfig():

config = mainAgent.getConfig()

println( config.subAgentCount )  // Number of sub-agents

// Sub-agent details
config.subAgents.each( agent => {
    println( "Name: #agent.name#" )
    println( "Description: #agent.description#" )
} )

How Sub-Agents Work

When you add a sub-agent, it is automatically converted to a tool:

1. Tool Name: delegate_to_{agent_name} (lowercase, special characters replaced with underscores)

2. Tool Description: Includes the sub-agent's name and description

3. Tool Parameter: A task parameter for the query to delegate

The parent agent's AI model decides when to use the delegation tool based on the task context.

// Behind the scenes, adding a sub-agent creates a tool like:
// Tool name: "delegate_to_mathagent"
// Tool description: "Delegate a task to the 'MathAgent' sub-agent..."
// The tool calls: subAgent.run( task )

Event Interception

Agents fire events during execution:

// Listen to agent events
interceptor = {
    beforeAIAgentRun: function( data ) {
        writeLog( "Agent ${data.agent.getName()} starting with: ${data.input}" )
    },
    afterAIAgentRun: function( data ) {
        writeLog( "Agent completed. Response: ${data.response}" )
    }
}

// Register interceptor
BoxRegisterInterceptor( interceptor )

// Run agent - events will fire
agent.run( "Hello" )

📚 Agents with Document Loaders & RAG

Agents can leverage document loaders and vector memory to access knowledge bases and provide grounded, factual responses.

🔄 Agent RAG Workflow

Basic RAG Agent

Create an agent with access to a knowledge base:

// Step 1: Create vector memory
vectorMemory = aiMemory( "chroma", {
    collection: "product_docs",
    embeddingProvider: "openai",
    embeddingModel: "text-embedding-3-small"
} );

// Step 2: Ingest documents using loaders
result = aiDocuments( "/docs/products", {
    type: "directory",
    recursive: true,
    extensions: ["md", "txt", "pdf"]
} ).toMemory(
    memory  = vectorMemory,
    options = {
        chunkSize: 1000,
        overlap: 200
    }
);

println( "📚 Loaded #result.documentsIn# documents as #result.chunksOut# chunks" );

// Step 3: Create agent with vector memory
agent = aiAgent(
    name: "Product Support",
    description: "Product documentation specialist",
    instructions: "Answer questions using the product documentation. Always cite sources.",
    memory: vectorMemory
);

// Step 4: Query - agent automatically retrieves relevant docs
response = agent.run( "How do I configure SSL certificates?" );
// Agent retrieves relevant docs from vector memory and provides accurate answer

Multi-Source RAG Agent

Combine multiple knowledge bases:

// Create separate vector memories for different sources
productDocs = aiMemory( "chroma", { collection: "product_docs" } );
apiDocs = aiMemory( "chroma", { collection: "api_docs" } );
faqMemory = aiMemory( "chroma", { collection: "faq" } );

// Ingest different sources
aiDocuments( "/docs/products", { type: "directory" } ).toMemory( productDocs );
aiDocuments( "/docs/api", { type: "directory" } ).toMemory( apiDocs );
aiDocuments( "/docs/faq.md", { type: "markdown" } ).toMemory( faqMemory );

// Agent with access to all knowledge bases
agent = aiAgent(
    name: "Knowledge Assistant",
    description: "Multi-source documentation assistant",
    memories: [ productDocs, apiDocs, faqMemory ]
);

// Agent searches across all memory systems
response = agent.run( "Explain the authentication API" );

RAG Agent with Real-Time Data Tools

Combine document retrieval with live data access:

// Vector memory for static docs
docMemory = aiMemory( "chroma", { collection: "documentation" } );
aiDocuments( "/docs", { type: "directory" } ).toMemory( docMemory );

// Tool for real-time data
statusTool = aiTool(
    "check_system_status",
    "Check current system status and metrics",
    () => getCurrentSystemStatus()
);

// Agent with both RAG and real-time capabilities
agent = aiAgent(
    name: "System Assistant",
    instructions: "Answer questions using docs. Use status tool for real-time data.",
    memory: docMemory,
    tools: [ statusTool ]
);

// Agent uses docs for general questions
response = agent.run( "What are the system requirements?" );

// Agent uses tool for real-time status
status = agent.run( "Is the system currently running?" );

Custom Context Injection

Manually inject specific context into agent queries:

// Load specific documents
docs = aiDocuments( "/docs/security.pdf", "pdf" );

// Create agent
agent = aiAgent(
    name: "Security Advisor",
    instructions: "Provide security advice based on documentation"
);

// Inject documents as context
message = aiMessage()
    .system( agent.getInstructions() )
    .setContext( docs.map( d => d.content ).toList( "\n\n" ) )
    .user( "What are the password requirements?" );

response = agent.run( message.getMessages() );

Conditional Document Loading

Load documents based on user query:

agent = aiAgent(
    name: "Smart Assistant",
    description: "Intelligent document retrieval assistant"
);

function smartQuery( required string userQuery ) {
    // Determine which documents to load based on query
    var docs = [];

    if ( userQuery.contains( "API" ) ) {
        docs = aiDocuments( "/docs/api", "directory" );
    } else if ( userQuery.contains( "tutorial" ) ) {
        docs = aiDocuments( "/docs/tutorials", "directory" );
    } else {
        docs = aiDocuments( "/docs/general", "directory" );
    }

    // Inject relevant docs and query
    var context = docs.map( d => d.content ).toList( "\n\n" );
    var message = aiMessage()
        .system( agent.getInstructions() )
        .setContext( context )
        .user( userQuery );

    return agent.run( message.getMessages() );
}

// Usage
answer = smartQuery( "How do I use the API for authentication?" );

🔄 Agents with Transformers

Agents can use transformers to process their inputs and outputs for specialized workflows.

Output Transformation

Transform agent responses automatically:

import bxModules.bxai.models.transformers.TextCleanerTransformer;

// Create agent
agent = aiAgent(
    name: "Content Generator",
    instructions: "Generate content based on user requests"
);

// Transform output
cleaner = new TextCleanerTransformer({
    stripHTML: true,
    removeExtraSpaces: true
});

// Use in pipeline
pipeline = aiMessage()
    .user( "${prompt}" )
    .to( agent )
    .transform( r => r.content )
    .to( cleaner )
    .transform( cleaned => {
        return {
            cleaned: cleaned,
            wordCount: cleaned.listLen( " " ),
            charCount: len( cleaned )
        }
    } );

result = pipeline.run({ prompt: "Write about BoxLang AI" });
println( "Word count: #result.wordCount#" );

Input Processing

Pre-process user input before sending to agent:

// Input transformer
inputCleaner = aiTransform( input => {
    return input
        .trim()
        .reReplace( "[^\w\s]", "", "all" )  // Remove special chars
        .reReplace( "\s+", " ", "all" );     // Normalize spaces
} );

agent = aiAgent(
    name: "Clean Input Agent",
    instructions: "Process cleaned user inputs"
);

// Pipeline with input transformation
pipeline = inputCleaner
    .transform( cleaned => aiMessage().user( cleaned ) )
    .to( agent );

response = pipeline.run( "   What  is  BoxLang???   " );
// Input is cleaned before reaching agent

Structured Output from Agents

Use transformers to extract structured data from agent responses:

agent = aiAgent(
    name: "Data Extractor",
    instructions: "Extract structured information from text"
);

// Transformer to parse JSON responses
jsonParser = aiTransform( response => {
    try {
        return jsonDeserialize( response.content );
    } catch( any e ) {
        return { error: "Invalid JSON", raw: response.content };
    }
} );

// Pipeline: agent → extract content → parse JSON
pipeline = aiMessage()
    .user( "Extract person data from: ${text}" )
    .to( agent )
    .transform( r => r.content )
    .to( jsonParser );

data = pipeline.run({ text: "John Doe, age 30, [email protected]" });
println( "Name: #data.name#" );

Multi-Stage Agent Processing

Chain multiple agents with transformers between them:

// Agent 1: Research
researcher = aiAgent(
    name: "Researcher",
    instructions: "Research topics thoroughly"
);

// Agent 2: Summarizer
summarizer = aiAgent(
    name: "Summarizer",
    instructions: "Create concise summaries"
);

// Agent 3: Editor
editor = aiAgent(
    name: "Editor",
    instructions: "Polish and format content"
);

// Transformer between stages
formatter = aiTransform( text => {
    return {
        text: text,
        sections: text.split( "\n\n" ),
        wordCount: text.listLen( " " )
    }
} );

// Multi-stage pipeline
pipeline = aiMessage()
    .user( "Research ${topic}" )
    .to( researcher )
    .transform( r => "Summarize: " & r.content )
    .to( summarizer )
    .transform( r => r.content )
    .to( formatter )
    .transform( data => "Edit: " & data.text )
    .to( editor );

result = pipeline.run({ topic: "Quantum Computing" });

Best Practices

1. Provide Clear Instructions

// Good: Specific instructions
agent = aiAgent(
    name: "SupportAgent",
    description: "Customer support specialist",
    instructions: """
        You are a friendly customer support agent.
        - Always be polite and professional
        - Ask clarifying questions when needed
        - Provide step-by-step solutions
        - Use tools to look up order information
        - Escalate complex issues to human agents
    """
)

2. Choose Appropriate Tools

// Only add tools the agent actually needs
agent = aiAgent(
    name: "WeatherAgent",
    tools: [ weatherTool ]  // Don't add unrelated tools
)

3. Manage Memory Lifecycle

// Clear memory at appropriate times
agent = aiAgent( name: "SessionAgent", memory: aiMemory( "simple" ) )

// Process request
agent.run( "Help me with task X" )

// When session ends or topic changes
agent.clearMemory()

4. Set Appropriate Parameters

// For creative tasks: higher temperature
creativeAgent = aiAgent(
    name: "Writer",
    params: { temperature: 0.8, max_tokens: 1000 }
)

// For factual tasks: lower temperature
factualAgent = aiAgent(
    name: "Analyzer",
    params: { temperature: 0.2, max_tokens: 500 }
)

5. Handle Errors Gracefully

try {
    response = agent.run( userInput )
} catch ( any e ) {
    writeLog( "Agent error: ${e.message}", "error" )
    // Fallback logic
    response = "I encountered an error. Please try again."
}

Real-World Examples

Customer Support Agent

lookupOrderTool = aiTool(
    "lookup_order",
    "Look up order details by order ID",
    orderId => getOrderDetails( orderId )
).describeOrderId( "The order ID to look up" )

checkInventoryTool = aiTool(
    "check_inventory",
    "Check product inventory",
    productId => getInventory( productId )
).describeProductId( "The product ID to check" )

supportAgent = aiAgent(
    name: "SupportBot",
    description: "Customer support specialist",
    instructions: "Help customers with orders and inventory questions. Be friendly and efficient.",
    tools: [ lookupOrderTool, checkInventoryTool ],
    memory: aiMemory( "simple" )
)

// Customer interaction
response = supportAgent.run( "What's the status of order #12345?" )
// Agent uses lookup_order tool and responds with order details

Code Review Agent

lintTool = aiTool(
    "lint_code",
    "Run linter on code",
    code => runLinter( code )
).describeCode( "The code to lint" )

testTool = aiTool(
    "run_tests",
    "Run unit tests",
    testFile => runTests( testFile )
).describeTestFile( "Path to test file" )

reviewAgent = aiAgent(
    name: "CodeReviewer",
    description: "Expert code reviewer",
    instructions: """
        Review code for:
        - Best practices
        - Security vulnerabilities
        - Performance issues
        - Test coverage
        Use lint_code and run_tests tools to validate code quality.
    """,
    tools: [ lintTool, testTool ],
    params: { temperature: 0.3 }
)

review = reviewAgent.run( "Review this code: ${codeSnippet}" )

Research Assistant

searchTool = aiTool(
    "search_web",
    "Search the web for information",
    query => performWebSearch( query )
).describeQuery( "Search query" )

researchAgent = aiAgent(
    name: "Researcher",
    description: "Research assistant",
    instructions: "Research topics thoroughly. Use web search when needed. Cite sources.",
    tools: [ searchTool ],
    memory: aiMemory( "simple" )
)

// Multi-turn research conversation
researchAgent.run( "Research quantum computing trends" )
researchAgent.run( "What are the top 3 companies in this space?" )
researchAgent.run( "Compare their approaches" )

// Get full conversation
conversation = researchAgent.getMemoryMessages()

Next Steps

• Explore Memory Systems for conversation history and context management

• See Vector Memory for semantic search and RAG workflows

• Learn about RAG Pipelines for complete document-to-answer workflows

• See Document Loaders for loading data from various sources

• Learn about Transformers for data processing in pipelines

• See Message Context for injecting security and RAG data into agents

• See Custom Memory for building custom memory implementations

• Learn about Tools for function calling patterns

• See Events for agent event handling

• Check Pipeline Overview for advanced agent workflows