It's been a while since we've shipped something this big. BoxLang AI 3.0 is a ground-up rethink of how AI agents, models, and tools work in the BoxLang ecosystem — and it lands with ten major features at once.

The headline is the AI Skills system: a first-class implementation of Anthropic's Agent Skills open standard that lets you define reusable knowledge blocks: coding styles, domain rules, tone policies, API guidelines once in a SKILL.md file and inject them into any number of agents and models at runtime. No more copy-pasting the same system-prompt boilerplate everywhere. Skills are versioned, composable, and come in two modes: always-on (full content in every call) and lazy (only a name + description until the LLM asks for more).

But that's just the start. Here's everything landing in 3.0:

• 🎯 AI Skills System — composable, file-based knowledge blocks injected into any agent or model at runtime
• 🔌 MCP Server Seeding — agents auto-discover and register tools from any MCP server
• 🗄️ Global AI Tool Registry — register tools by name once, reference them as strings anywhere
• 🔧 Tool System Overhaul — new BaseTool / ClosureTool architecture plus two built-in core tools
• 🛡️ Provider Capability System — type-safe capability detection with clear UnsupportedCapability errors
• 🌲 Parent-Child Agent Hierarchy — multi-agent orchestration trees with cycle detection and depth tracking
• 🧵 Middleware Support — six built-in middleware classes for logging, retries, guardrails, and more
• 🏢 Stateless Agents + Per-Call Identity Routing — safe multi-tenant memory across concurrent requests
• 🤗 HuggingFace Embeddings — new provider for the HuggingFace Inference API
• 🔀 Custom Service URLs — proxy and self-hosted endpoint support across all providers

Read the full changelog here: https://ai.ortusbooks.com/readme/release-history/3.0.0

If you've been building AI-powered apps with BoxLang, this release changes everything. If you haven't started yet, this is the release that makes it worth it.

Let's dig in. 🎉

---

🎯 The Headline: AI Skills System

The single biggest addition in 3.0 is the AI Skills system — a first-class implementation of Anthropic's Agent Skills open standard.

Think of a skill as a portable, reusable unit of expertise: a SQL coding style guide, a tone-of-voice policy, domain-specific rules, API cheat sheets — anything your AI should know before it starts answering. Define it once in a SKILL.md file. Inject it into any number of agents and models at runtime. No more copy-pasting the same system-prompt boilerplate across every agent you build.

// Load a skill from a file
apiSkill = aiSkill( ".ai/skills/api-guidelines/SKILL.md" )

// Load every skill in a directory tree
allSkills = aiSkill( ".ai/skills/", recurse: true )

// Inline skill for short, self-contained guidance
sqlStyle = aiSkill(
    name        : "sql-style",
    description : "SQL coding standards",
    content     : "Always use snake_case. Prefer CTEs. Never use SELECT *."
)

Skills come in two injection modes:

• Always-on — full content in every LLM call. Zero latency. Best for short, universally relevant rules like tone and formatting.
• Lazy — only a name + one-line description goes into the system message. The LLM calls a built-in loadSkill( name ) tool to fetch the full content on demand. Perfect for large skill libraries where most skills are irrelevant to most queries — keeps your token usage low.

You can even promote a lazy skill to always-on mid-session:

// After the user mentions SQL work, pre-load it for the rest of the conversation
agent.activateSkill( "sql-style" )

And if you want certain skills available to every agent in your application without explicitly passing them:

// In Application.bx — every agent inherits these automatically
aiGlobalSkills().add( aiSkill( ".ai/skills/company-tone/SKILL.md" ) )
aiGlobalSkills().add( aiSkill( ".ai/skills/security-policy/SKILL.md" ) )

Skills live in plain Markdown files — which means your team can review them in pull requests, diff them, and keep them in sync with the rest of your codebase. This is the end of prompt drift.

---

📚 Brand New Docs

The entire documentation has been re-organized so you can go from zero to hero. Tons of new sections and more direct docs for your reading pleasure: https://ai.ortusbooks.com/

🔌 MCP Server Seeding

Agents can now be pointed directly at one or more MCP servers. All tools exposed by those servers are discovered automatically via listTools() and registered as MCPTool instances — no manual tool construction required.

agent = aiAgent(
    name       : "data-analyst",
    mcpServers : [
        { url: "http://localhost:3001", token: "secret" },
        "http://internal-tools-server:3002"
    ]
)

Or fluently:

agent = aiAgent( "analyst" )
    .withMCPServer( "http://localhost:3001", { token: "secret" } )
    .withMCPServer( mcpClientInstance )

The agent's system prompt is automatically updated so the LLM knows which tools came from which server. MCP servers are also surfaced in getConfig() output for full observability.

---

🗄️ Global AI Tool Registry

New in 3.0: a module-scoped Global Tool Registry accessible via the aiToolRegistry() BIF. Register tools by name once — in Application.bx or ModuleConfig.bx — and reference them as plain strings anywhere in your codebase.

// Register once
aiToolRegistry().register( "searchProducts", productSearchTool )
aiToolRegistry().register( "getWeather@myapp", weatherTool )

// Reference by name anywhere — no live object references needed
result = aiChat(
    "Find wireless headphones under $50",
    { tools: [ "searchProducts", "getWeather@myapp" ] }
)

Module namespacing (e.g. now@bxai) keeps registrations collision-free across modules. Two new interception points — onAIToolRegistryRegister and onAIToolRegistryUnregister — give you hooks for auditing and lifecycle management.

---

🔧 Tool System Overhaul

The tool system has been significantly redesigned around a new BaseTool abstract base class. All tool implementations extend it, getting the shared invocation lifecycle, result serialization, and fluent describeArg() annotation syntax for free.

The old Tool.bx is replaced by ClosureTool — a BaseTool subclass backed by any closure or lambda that auto-introspects the callable's parameter metadata to generate an OpenAI-compatible function schema.

searchTool = aiTool(
    "searchKB",
    "Search the knowledge base",
    function( required string query, numeric maxResults = 5 ) {
        return knowledgeBase.search( query, maxResults )
    }
)

Two built-in core tools ship with the module:

• now@bxai — auto-registered on module load, returns the current date/time in ISO 8601. Every agent gets temporal awareness for free, with no configuration.
• httpGet — opt-in only (not auto-registered for security), fetches any URL via HTTP GET.

now@bxai being auto-registered is worth calling out. No major AI framework ships built-in tools out of the box. This is a genuine differentiator — your agents just know what time it is without any wiring on your part.

---

🛡️ Provider Capability System

A new type-safe capability system prevents calling unsupported operations on providers and gives you clear, actionable errors instead of cryptic runtime crashes.

service = aiService( "voyage" )
println( service.getCapabilities() )          // [ "embeddings" ]
println( service.hasCapability( "chat" ) )    // false

aiChat(), aiChatStream(), and aiEmbed() now check provider capabilities before calling and throw a clean UnsupportedCapability exception if the requirement isn't met. No more debugging mysterious provider errors.

---

🌲 Parent-Child Agent Hierarchy

Multi-agent orchestration is now a first-class concept. AiAgent tracks its position in an agent tree with full introspection, cycle detection, and depth tracking.

coordinator = aiAgent( name: "coordinator" )
    .addSubAgent( aiAgent( name: "researcher" ) )
    .addSubAgent( aiAgent( name: "writer" ) )

println( coordinator.isRootAgent() )         // true
println( researcherAgent.getAgentDepth() )   // 1
println( writerAgent.getAgentPath() )        // /coordinator/writer
println( researcherAgent.getAncestors() )    // [ coordinator ]

addSubAgent() automatically wires the parent relationship. getConfig() exposes parentAgent, agentDepth, and agentPath for full observability.

---

🧵 Middleware Support

Both AiModel and AiAgent now support composable middleware for cross-cutting concerns — logging, retries, guardrails, human-in-the-loop approvals, and more. Agent middleware is prepended ahead of model middleware in the execution chain.

3.0 ships six middleware classes out of the box:

Middleware	What It Does
LoggingMiddleware	Audit every LLM call and tool invocation
RetryMiddleware	Exponential back-off for rate limits and transient errors
GuardrailMiddleware	Block dangerous tools and validate arguments with regex
MaxToolCallsMiddleware	Cap tool invocations per run to prevent runaway agents
HumanInTheLoopMiddleware	Require explicit human approval before sensitive tools execute
FlightRecorderMiddleware	Record real runs to JSON fixtures, replay offline in CI

The FlightRecorderMiddleware deserves a special mention — it's a testing superpower. Record a live agent run once, commit the fixture, and replay it deterministically in CI with zero live provider calls.

// Record a real run
agent = aiAgent( "weather-bot", middleware: new FlightRecorderMiddleware( mode: "record" ) )
agent.run( "What is the weather in London?" )
// → Writes: .ai/flight-recorder/weather-bot-<timestamp>.json

// Replay in CI — no live calls, fully deterministic
agent = aiAgent(
    "weather-bot",
    middleware: new FlightRecorderMiddleware(
        mode        : "replay",
        fixturePath : "tests/fixtures/weather-bot.json"
    )
)

---

🏢 Stateless Agents + Per-Call Identity Routing

AiAgent is now fully stateless. userId and conversationId are resolved per-call from the options argument, eliminating shared-state concurrency bugs in multi-user deployments.

Every memory type (IAiMemory, IVectorMemory) now accepts optional userId and conversationId on add(), getAll(), clear(), and related methods — so a single memory instance can safely serve multiple tenants:

sharedMemory = aiMemory( "cache" )

sharedMemory.add( message, userId: "alice", conversationId: "conv-1" )
sharedMemory.add( message, userId: "bob",   conversationId: "conv-2" )
sharedMemory.getAll( userId: "alice", conversationId: "conv-1" )

---

What Else Is New

• 🤗 HuggingFace Embeddings — new huggingface provider for the HuggingFace Inference API
• 🔀 Custom Service URLs — all senders now accept a baseUrl override for proxies, self-hosted endpoints, and OpenAI-compatible APIs
• 🏗️ BaseService → OpenAIService split — BaseService is now truly provider-agnostic, making custom provider implementations much cleaner
• 🐛 Streaming event fixes — beforeAIModelInvoke/afterAIModelInvoke events were not firing for streaming; fixed
• 🐛 MCP requestId null crash — fixed a crash on JSON-RPC notifications that intentionally omit id

---

No Breaking Changes

3.0 is a major release but your existing code keeps working. aiChat(), aiEmbed(), and aiAgent() BIF signatures are unchanged. Upgrade, run your tests, and start exploring the new APIs.

---

Get Started

# Install or upgrade your OS installation via BoxLang
install-bx-module bx-ai

# Install or upgrade via CommandBox
install bx-ai

📖 Full Documentation 🛠️ Changelog 🐛 Report Issues 💬 Community Slack