クイックスタート

プロジェクトの全ライフサイクル: スキャフォールド、編集、ビルド、実行。

クイックスタート

BX Agents プロジェクトの全ライフサイクル - スキャフォールド、編集、ビルド、実行 - を一通り確認します。

1. プロジェクトをスキャフォールドする

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

--model は必須です (provider/model スラッグです - どう解析されるかは Agent.bx を参照)。--name と --description は任意で、--name のデフォルトは対象ディレクトリ自身の名前です。

これにより、以下が作成されます。

my-agent/
├── Agent.bx
├── instructions.md
├── tools/
├── skills/
├── subagents/
├── models/
├── gateways/
├── schedules/
├── mcp/
├── interceptors/
├── modules/
└── tests/
    ├── box.json
    └── specs/
        └── AgentSpec.bx

Agent.bx は次のようになります。

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

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

}

これは bx-ai 自身の AiAgent を extends するので、それ自体がエージェントです - 継承して、あなたのエージェントに必要なものをクラスに直接追加してください。詳しくは Agent.bx を参照してください。

すべてのコンベンションフォルダは空の状態で作成されます - 実際にエージェントが必要とするフォルダにファイルを追加し、残りは削除する (あるいは単に無視する) だけです。

2. 編集する

instructions.md を開き、エージェントのシステムプロンプトを書きます。ツールを追加します。

// tools/Greeter.bx
class {

	@AITool( "Say hello to someone by name." )
	function sayHello( name ) {
		return "Hello, " & arguments.name & "!";
	}

}

他のすべてのフォルダ (skills/、subagents/、gateways/、schedules/、mcp/、interceptors/、models/、modules/) については コンベンション セクションを参照してください。

3. テストする

cd tests && box install && cd ..   # once, to fetch testbox/
bxAgents test

スキャフォールドされた tests/specs/AgentSpec.bx はそのまま合格します - mock プロバイダーに対してエージェントをビルドし (API キーもネットワークも不要)、スクリプト化された応答をアサートします。自分のスペックで使える mockResponses() とカスタムマッチャー (toHaveCalledTool など) については tests/ を参照してください。

4. ビルドする

bxAgents build

ビルドパイプライン 全体 - config の解決、発見、検証、コード生成、マニフェストの正規化 - を実行し、実際の ColdBox アプリケーションを .build/app/ に、加えて .build/manifest.json を書き込みます。Agent.bx の環境オーバーライドに対してビルドするには bxAgents build --environment=production を実行してください (Agent.bx 参照)。

プロジェクトが検証に失敗した場合 (重複したツール名、不正な cron 式、未知のモデルプロバイダーなど)、build は最初のエラーだけでなく、収集されたすべてのエラーとともに失敗します。

5. 実行する

ビルド済みエージェントと対話する方法は 2 通りあり、どちらも同一の GeneratedAgentFactory.bx をロードし、まったく同じエージェントツリーを構築するため、決して食い違うことはありません。

対話的に、ターミナルから:

bxAgents chat

HTTP 経由で、実際の boxlang-miniserver プロセスを通じて:

bxAgents serve --port=8080

プロジェクトに { exposes: "agent", path: "/api/chat" } を持つ gateways/* エントリがあれば、エージェントは POST http://localhost:8080/api/chat/invoke (および /stream、/batch、/info - gateways/ 参照) で到達可能になります。

6. 確認、パッケージ化、デプロイ

bxAgents inspect              # pretty-print .build/manifest.json
bxAgents package --version=1.0.0   # writes dist/my-agent-1.0.0.bxa + .sha256
bxAgents deploy --destination=/path/to/somewhere   # copies the newest .bxa there

マニフェスト と デプロイとシークレット を参照してください。

7. 後片付け

bxAgents clean

.build/ と dist/ のみを削除します - あなたのソースのコンベンション (Agent.bx、tools/ など) は一切触れられません。

次のステップ

• コンベンション で、すべてのコンベンションフォルダを一通り確認する。
• examples/ にある、実際に動くサンプルプロジェクトを見る。
• CLI リファレンス で、すべての動詞のフラグを確認する。