BX Agents

フォルダとファイルでエージェントを記述し、実際に動く ColdBox アプリケーションへとビルドします。

BX Agents は BoxLang 向けの、コンベンションベースの AI エージェントフレームワークです。 ColdBox と BX AI の上に構築されています。エージェントはフレームワークの API を直接扱うのではなく、ファイルとフォルダで記述します。すると bxAgents build がそこから実際に動く、実行可能な ColdBox アプリケーションを組み立てます。

ビルド時に組み立てる

発見・検証・コード生成は起動のたびにではなく、一度だけ実行されます。ビルド後に実行するのはただの ColdBox アプリです。

フォルダが API

Agent.bx と instructions.md だけが必須ファイルです。それ以外のコンベンションフォルダはすべて任意で、存在する場合にのみ出力に反映されます。

ツールとスキル

@AITool 注釈付きの関数を tools/ に置くか、SKILL.md フォルダを skills/ に置くだけで、どちらも自動的に検出・組み込みされます。

どこまでもエージェント

subagents/ はまったく同じコンベンションツリーを入れ子にできるので、専門家チームは単にフォルダを増やすだけで作れます - リーフ (末端) から先にビルドされます。

12 種類のゲートウェイ

Telegram、Slack、Discord、Email、WhatsApp、Teams、Twilio、GitHub、Signal に加え、http、 cli、mock。

Web チャット UI を自動生成

Agent.bx でリクエストすれば、ビルドがセッション履歴付きの、テーマ変更可能なストリーミングチャットフロントエンドを生成します。

4 ステップでエージェントを構築する

インストール

install-bx-module bx-ai bx-agents

box install bx-ai,bx-agents

スキャフォールド

bxAgents new my-agent --model=openai/gpt-5

続いて instructions.md を編集し、必要なコンベンションフォルダを追加します。

ビルド

bxAgents build

発見・検証・マニフェスト生成・コード生成を行い .build/app/ に出力します。

対話する

bxAgents chat
# または HTTP で公開する:
bxAgents serve --port=8080

`build` が実際に生成するもの

あなたのコンベンションツリーと、build がそれを変換する、ただの ColdBox アプリケーション。

your-agent/
├── Agent.bx           # name, model, description
├── instructions.md    # the system prompt
├── tools/             # @AITool functions
├── skills/            # SKILL.md capabilities
├── subagents/         # nested agent trees
├── models/            # named model configs
├── gateways/          # HTTP/MCP/chat exposure
├── schedules/         # a real ColdBox scheduler
├── mcp/               # MCP servers you host
├── interceptors/      # lifecycle hooks
└── modules/           # module dependencies

.build/app/
├── Application.bx
├── config/
│   ├── ColdBox.bx
│   ├── WireBox.bx
│   ├── Router.bx
│   └── Scheduler.bx
├── agent/
│   └── GeneratedAgentFactory.bx
├── tools/  skills/  mcp/
├── handlers/  interceptors/
└── index.bxm

なぜリクエスト時ではなくビルド時に組み立てるのか?

多くのエージェントフレームワークは、起動のたびに、リクエスト時にツール・スキル・ルート・スケジュールを配線します。BX Agents はその逆です。bxAgents build が発見・検証・コード生成を正確に一度だけ実行し、.build/app/ の下にただの ColdBox アプリケーションを生成します。

それを起動する - bxAgents serve 経由でも、実際の boxlang-miniserver プロセスでも、BoxLang が動くどこにでもデプロイできるポータブルな .bxa でも - あとは通常のアプリを起動するのと同じです。コンベンションのスキャンも、動的なファイル走査も、リクエストパスに先送りされるビルド時作業も一切ありません。

まずは 1 ファイルから始める

必須なのは Agent.bx だけです。instructions.md は任意です - クラス内で直接 instructions を設定してもよいですし、ファイルを置いてビルドに組み込ませることもできます。他のフォルダはすべて、それが存在し、かつ中身がある場合にのみ生成出力に影響します - つまり実際に必要になった時点でコンベンションを足していけます。

Agent.bx こそがエージェントである

Agent.bx は BX AI 自身の AiAgent を直接 extends します - ビルドは config 構造体から再構築するのではなく、あなたのクラスをそのままインスタンス化するので、書いたものがそのまま実行されます。IDE も他の通常のクラスと同じように解析できます。詳しくは Agent.bx を参照してください。

どこからでも到達できるように

チャットプラットフォーム

9 種類の push 型ゲートウェイ - Telegram、Slack、Discord、Email、WhatsApp Cloud、Teams、Twilio、 GitHub、Signal - を、queue / steer / interrupt ポリシーを持つ 1 つのセッションが調整します。

HTTP と MCP

エージェントを HTTP ルートとして公開したり、mcp/ からローカル MCP サーバーをホストして他のクライアントからツールを呼び出せるようにします。

出荷する

ポータブルな .bxa をパッケージ化し、local、ssh、docker、digitalocean、 ftp、sftp のいずれかでデプロイします - シークレットは常に環境変数のままで、ビルド成果物には決して含まれません。