Agent.bx

唯一の必須ファイル - bx-ai 自身の AiAgent を extends するクラスなので、それ自体がエージェントである。

Agent.bx

Agent.bx は BX Agents プロジェクトで唯一の必須ファイルです。これは bx-ai 自身の AiAgent を extends するので、それ自体がエージェントです - ビルドは config 構造体から再構築するのではなくこれをそのままインスタンス化するので、書いたものがそのまま実行されます。継承して、必要なものを何でも追加してください。プライベートヘルパー、オーバーライドしたメソッド、コード内で登録したツールなど何でもです。構造体を返すディスクリプタではなく実際のクラスなので、IDE は他の通常の BoxLang クラスと同じように解析できます - 定義へのジャンプ、継承メソッドの補完、すべてです。

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "my-agent",
			description : "A helpful assistant",
			instructions: "You are a helpful assistant.",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

}

bxAgents new はまさにこの形をスキャフォールドします。instructions.md は任意です - super.init() の中で instructions を直接設定しても、Agent.bx の隣にファイルを置いてビルドに組み込ませてもかまいません (下の表を参照)。

クラスの上にビルドが積み重ねるもの

ルール: 明示的に宣言されたコンベンションが勝ち、そうでなければクラスが主導します。

そのため、すべてを自身の init() で設定するエージェントには何も強制されず、最低限しか設定しないエージェントでも、自分が言及しなかったコンベンションはきちんと取り込まれます。以下はすべて任意です - これらのキーのいずれかを返す configure() を宣言すれば、クラス自身が設定したものや、対応する instructions.md/tools//subagents/ コンベンションフォルダを上書きできます。

このクラスは生成されたアプリの agent/classes/ にコピーされ、そこで自身の絶対ファイルパスによってインスタンス化されます (登録されたマッピングに依存する相対的な参照は決して使いません)。tools/、skills/、mcp/ がコピーされるのとまったく同じ方法です - そのため、パッケージ化された .bxa はこれを保持し、実際の ColdBox コンテナが起動しているかどうかに関わらず chat/invoke/serve はすべて同じ方法でこれをインスタンス化します。

configure() (任意) - クラスの設定を上書きする

configure() メソッドは完全に任意です。クラスの外部から特定のフィールドだけを上書きしたい場合にのみ宣言してください - デプロイ固有の値 (環境ごとに異なるモデルなど) をクラス本体の外に保つのに便利です。

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name  : "with-mcp-servers-agent",
			model : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function configure() {
		return {
			mcpServers : [
				"https://example.com/mcp",
				{ url : "https://other.com/mcp", name : "other" }
			]
		};
	}

}

The model slug

model は BX Agents 独自のコンベンションです - bx-ai 自身は provider と model を aiModel() への 2 つの別々の引数として受け取ります。BX Agents はスラッグを最初の / だけで分割するので、それ自体にスラッシュを含むプロバイダー (OpenRouter の openrouter/anthropic/claude-x のような) でも正しく解析されます。

model に / がまったく含まれない場合、既知のコアプロバイダー名か、models/ エントリの名前のいずれかに一致する必要があります - それ以外は検証で拒否されます。認識されているコアプロバイダーは次の通りです: bedrock、claude、cohere、deepseek、docker、elevenlabs、gemini、grok、groq、huggingface、minimax、mistral、mock、ollama、openai、openai-compatible、openrouter、perplexity、voyage (bx-ai 自身の CORE_PROVIDERS と同期しています)。mock は実在するプロバイダーで、テストや CI に便利です - ネットワーク呼び出しを一切行いません。

このスラッグ分割のコンベンションは、configure() で宣言された model 文字列が通過するものです - super.init() 自身の model 引数は代わりに実際の AiModel インスタンスを直接受け取ります (aiModel( provider: "...", params: { model: "..." } ))。クラスがすでに bx-ai 自身の API を話しているためです。

環境オーバーライド

Agent.bx は、環境にちなんだ名前のメソッド (例えば production()、development()、または任意のカスタム名) を宣言し、オーバーライドの構造体を返すことができます - これはクラスが configure() を宣言しているかどうかに関わらず機能します。

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "override-agent",
			description : "An agent with an environment override",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function production() {
		return {
			model : "openai/gpt-5-mini"
		};
	}

}

アクティブな環境は、次の優先順位で解決されます (最上位が優先されます)。

1. --environment CLI フラグ (bxAgents build --environment=production)
2. BX_AGENTS_ENV 環境変数
3. "development" (デフォルト)

これはビルド時の決定のみで、ColdBox 自身のランタイム環境検出 (生成されたアプリは ColdBox の environments コンベンションに従って自身で getSetting("environment") を読み取ります) とは別物です - この優先順位は、Agent.bx のどの environment() オーバーライドメソッド、そしてどの boxlang-{env}.json/miniserver-{env}.json ファイルをビルドパイプラインが適用するかだけを決定します。

アクティブな環境に一致するメソッドが存在しない場合、オーバーライドは適用されません。

マージのセマンティクス

完全な解決順序 (優先度の低い順から高い順) は次の通りです。

1. configure() (任意)
2. 一致する環境オーバーライドメソッド (あれば)
3. boxlang.json
4. boxlang-{environment}.json
5. miniserver.json
6. miniserver-{environment}.json

構造体のキーは再帰的にマージされます - より優先度の高いソースにあるネストされた構造体は、それが実際に設定しているキーだけを上書きし、より優先度の低いソースにある兄弟キーはそのまま残されます。配列とすべてのスカラー値は、追加や連結ではなく丸ごと置き換えられます。

boxlang.json/boxlang-{env}.json/miniserver.json/miniserver-{env}.json はすべて任意のプロジェクトルート JSON ファイルで、BoxLang コードよりもデータとして表現しやすい config (例えばモデルのデフォルト値) に便利です。

// boxlang.json
{
	"modelDefaults": { "temperature": 0.7, "maxTokens": 1000 }
}

// boxlang-production.json
{
	"modelDefaults": { "temperature": 0.2 }
}

ここで --environment=production でビルドすると modelDefaults: { temperature: 0.2, maxTokens: 1000 } になります - 再帰的マージにより、boxlang-production.json が一切言及していない maxTokens はベースファイルから保持されます。