Studio キャンバス操作ガイド

本ドキュメントでは、AgentCraftLab Workflow Studio のインターフェース構成と操作方法について説明します。

1. インターフェース概要

Studio ページは4つの主要エリアで構成されています：

エリア	位置	説明
Node Palette	左側パネル	ノードパレット。使用可能なすべてのノードタイプが表示され、キャンバスにドラッグ＆ドロップできます
Canvas キャンバス	中央エリア	React Flow キャンバス。ノードの配置、接続、ワークフローの組み立てを行います
Properties Panel	右側フローティングパネル	ノードを選択すると表示され、そのノードのすべてのプロパティを編集できます
Chat Panel	最右側パネル	Execute と AI Build の2つのタブがあり、折りたたみやドラッグで幅を調整できます

キャンバス上部には Top Bar ツールバー があり、左から順に以下の機能が並んでいます：

ファイル操作：Load / Save / Import
キャンバスツール：Auto Layout / Settings / Templates / Save as Template
出力：Code Generation / Export

キャンバス下部には Console Panel があり、実行時のログ出力が表示されます。

Node Palette ノード分類

ノードパレットは2つのグループに分かれています：

Nodes（コアノード）： Agent、Tool、RAG、Condition、Loop、Router、Human、Code、Iteration、Parallel、Autonomous

Integrations（統合ノード）： A2A Agent、HTTP Request

左上の矢印アイコンをクリックすると、Node Palette を折りたたみ、アイコン列のみの表示にできます。

2. 基本操作

2.1 ノードの追加

左側の Node Palette からノードをキャンバスにドラッグ＆ドロップして追加します。マウスを離すと、ノードは 20px グリッドに自動的にスナップされます。

右クリックメニューからも、よく使うノード（Agent、Condition、Human、Code、Parallel、Iteration）をすばやく追加できます。

2.2 ノードの接続

ノード下部の出力ハンドルから別のノードの入力ハンドルへ接続線をドラッグします。システムは接続の妥当性を自動的に検証します：

自分自身への接続は不可
Start ノードへの入力接続は不可
End ノードからの出力接続は不可
RAG ノードは Agent ノードとのみ接続可能

接続線はデフォルトで smoothstep スタイルを使用します。接続線をクリックして選択し、選択後に Delete キーで直接削除できます（確認不要）。

2.3 ノードの選択と削除

ノードをクリックして選択すると、右側に Properties Panel が表示されます
Delete または Backspace キーで選択中のノードを削除します（確認ダイアログが表示されます）
キャンバスの空白部分をクリックすると選択が解除されます

2.4 ノードの複製

ノードを選択した状態で Ctrl+D を押すと、ノードが複製されます。複製されたノードは元のノードの近くに配置されます。

2.5 Undo / Redo（元に戻す / やり直し）

Ctrl+Z：直前の操作を元に戻す
Ctrl+Y：操作をやり直す
最大50ステップまで遡れます

2.6 Auto Layout 自動レイアウト

ツールバーの Auto Layout ボタンをクリックすると、システムがすべてのノードを自動的に再配置し、アニメーション付きで画面に合わせてビューを調整します。

2.7 クイック保存

Ctrl+S を押すと保存ダイアログが開きます。既に保存記録がある場合は直接上書きできます。初回保存時は名前の入力が必要です。

2.8 右クリックメニュー

キャンバス上で右クリックするとコンテキストメニューが開きます：

空白部分で右クリック：ノードのクイック追加メニューを表示
ノード上で右クリック：Duplicate（複製）、Delete（削除）、Auto Layout（自動レイアウト）オプションを表示

Escape キーで右クリックメニューを閉じることができます。

2.9 ワークフローのインポート

ツールバーの Import ボタンをクリックし、.json 形式のワークフローファイルを選択してインポートします。インポート後、現在のキャンバス上のすべてのコンテンツが置き換えられます。

3. Properties Panel プロパティパネル

任意のノードを選択すると、キャンバスの右側に Properties Panel がスライドアウトし、そのノードのプロパティを編集できます。ノードのタイプによって異なる設定項目が表示されます。一般的な項目は以下のとおりです：

名前 (Label)：キャンバス上でのノードの表示名
Instructions：エージェントのシステムプロンプト（全画面編集に展開可能）
モデル (Model)：エージェントが使用する LLM モデル
ツール (Tools)：接続されたビルトインツール、MCP Server、HTTP API
条件 / ルーティングルール：Condition、Router ノードの判定ロジック
Code 設定：Code ノードの変換モードとスクリプト

キャンバスの空白部分をクリックするとプロパティパネルが閉じます。

4. Chat Panel チャットパネル

Chat Panel はインターフェースの最右側にあり、左端をドラッグして幅を調整できます（280px〜800px）。折りたたみボタンをクリックして非表示にすることも可能です。

4.1 Execute タブ

現在のキャンバス上のワークフローを実行するために使用します：

入力ボックスにメッセージを入力します（ワークフローへの入力として使用）
添付ファイルボタンでファイルをアップロードできます
送信後、システムが AG-UI プロトコルでストリーミング応答を返します
実行中に Human ノードに到達すると、インタラクションパネルが表示されます（テキスト入力 / 選択 / 承認の3つのモード）

4.2 AI Build タブ

自然言語で要件を記述すると、AI がキャンバス上にワークフローを自動構築します：

AI Build タブに切り替えます
自然言語でワークフローを記述します（例：「カスタマーサポートボットを作成して、まず問題を分類してから専門家に回答を依頼する」）
AI がノード構成をストリーミングで生成し、キャンバスがリアルタイムで更新されます

AI Build は partial update 優先戦略（差分更新）を使用し、必要な場合のみ full rebuild を実行します。

5. Workflow Settings ワークフロー設定

ツールバーの歯車アイコンをクリックして設定ダイアログを開き、以下を構成できます：

変数 (Variables)

Variables タブでワークフロー変数を定義します。任意のノードで {{prefix:name}} 構文で参照できます。

層	構文	説明
システム	`{{sys:user_id}}`	読み取り専用：`user_id`、`timestamp`、`execution_id`、`workflow_name`、`user_message`
ワークフロー	`{{var:counter}}`	ユーザー定義変数（名前・型・デフォルト値）
環境	`{{env:API_URL}}`	サーバー環境変数（`AGENTCRAFTLAB_` プレフィックス必須）
ノード出力	`{{node:Agent-1}}`	前のノードの出力（既存機能）

変数の定義：Workflow Settings → Variables タブ → 変数を追加。名前、型（string / number / boolean / json）、デフォルト値を設定。

変数の参照：指示フィールドで {{ を入力するとオートコンプリートが表示されます。

Code ノードでの変数書き込み：JavaScript では $variables.name で読み取り。書き戻しは __variables__ と __output__ を含む JSON を返します：

javascript

const count = parseInt($variables.counter || '0') + 1;
return JSON.stringify({
  __variables__: { counter: String(count) },
  __output__: `${count} 件処理済み`
});

環境変数：サーバーで AGENTCRAFTLAB_API_URL=https://... を設定し、{{env:API_URL}} で参照（プレフィックスは自動除去）。

ミドルウェア (Middleware)

エージェントの ChatClient を順番にラップし、エンタープライズグレードのセキュリティとオブザーバビリティを提供します：

GuardRails — コンテンツセーフティガード

エージェントが不正なコンテンツを処理または生成しないように保護します。Middleware 設定パネルで以下を構成できます：

Scan All Messages：すべての会話メッセージをスキャン（最後の1件だけでなく）し、マルチターン攻撃を防止します
Scan Output：LLM の応答をスキャンし、モデルによる機密情報の漏洩を防止します
Injection Detection：プロンプトインジェクション攻撃を検出します（「前の指示を無視して」など）。9種類の中英パターンに対応
Blocked Terms：ブロックキーワード（カンマ区切り）。トリガー時に拒否メッセージを返します
Warn Terms：警告キーワード。警告を記録しますが通過を許可します
Regex Rules：正規表現ルール（1行に1つ）。複雑なパターンマッチングに使用します
Allowed Topics：エージェントが議論できるトピックを制限します（カンマ区切り）。トピックから逸脱すると自動的にブロックされます
Blocked Response：カスタムブロック応答メッセージ

PII Masking — 個人情報保護

個人識別情報（PII）を自動的に検出してマスキングします。GDPR/HIPAA/PCI-DSS のエンタープライズコンプライアンスに対応：

Protection Mode：
- Irreversible（不可逆）：PII を *** で置換し、LLM は元のデータを見ることができません
- Reversible（可逆）：PII を [EMAIL_1]、[PHONE_1] などのトークンで置換し、LLM の応答後に自動的に復元します
Region Rules：検出する地域フォーマットを選択します
- Global（Email、IP、クレジットカード、IBAN、URL、暗号通貨アドレス）
- Taiwan（身分証、電話、統一編号、健康保険カード、住所）
- Japan（マイナンバー、電話、パスポート、運転免許証）
- Korea（住民登録、電話、事業者登録）
- US（SSN、電話、パスポート、運転免許証）
- UK（NHS、NINO、パスポート、郵便番号）
Confidence Threshold：信頼度しきい値（0.0-1.0）。この値を下回る検出結果は無視されます
Scan Output：LLM の応答に含まれる PII をスキャンします
Custom Patterns：カスタム正規表現ルール

その他のミドルウェア

RateLimit：LLM 呼び出し頻度を制限します（Token Bucket アルゴリズム、デフォルトは毎秒5回）
Retry：失敗時の自動リトライ（指数バックオフ、最大3回）。HTTP 429/503 などの一時的なエラーに対応
Logging：各 LLM 呼び出しの入力、出力、所要時間を記録します

Hooks イベントフック

6つの挿入ポイントで、ワークフロー実行の特定段階にカスタムロジックを挿入できます：

Hook	トリガータイミング
OnInput	入力受信時
PreExecute	実行前
PreAgent	各エージェント実行前
PostAgent	各エージェント実行後
OnComplete	実行完了時
OnError	エラー発生時

各 Hook は2つのタイプをサポートしています：

code：TransformHelper によるデータ変換
webhook：指定 URL への HTTP POST 送信

また、BlockPattern により正規表現で特定のコンテンツをインターセプトできます。

6. Code Generation コード生成

ツールバーの Code ボタンをクリックすると、現在のワークフローを実行可能なコードに変換できます。3つの言語をサポートしています：

言語	説明
C#	Microsoft.Agents.AI フレームワークを使用し、.NET プロジェクトに直接統合可能
Python	Python 版の同等実装
TypeScript	TypeScript/Node.js 版の同等実装

生成されたコードはクリップボードにコピーして、プロジェクト開発にそのまま使用できます。

7. Export エクスポート

ツールバーの Export ボタンをクリックすると、4つのエクスポートモードから選択できます：

モード	説明
JSON	`.json` ファイルとしてエクスポート。バックアップや再インポートに使用
Web API	完全な .NET Web API デプロイパッケージを生成
Teams Bot	Microsoft Teams Bot デプロイパッケージを生成
Console App	.NET Console アプリケーションデプロイパッケージを生成

JSON 以外の3つのモードでは、完全なプロジェクト構造を含む圧縮ファイルが生成され、直接ビルドしてデプロイできます。

8. Save as Template テンプレートとして保存

ツールバーのブックマークアイコンをクリックし、テンプレート名を入力すると、現在のワークフローをカスタムテンプレートとして保存できます。保存後のテンプレートは Templates ダイアログに表示され、後から素早く読み込んで再利用できます。

カスタムテンプレートはバックエンドの永続化ストレージに同期されます。バックエンドが利用できない場合はローカルの fallback に切り替わります。

ショートカットキー一覧

ショートカット	機能
`Ctrl+S`	保存ダイアログを開く
`Ctrl+Z`	元に戻す（最大50ステップ）
`Ctrl+Y`	やり直し
`Ctrl+D`	選択中のノードを複製
`Delete` / `Backspace`	選択中のノードまたは接続線を削除
`Escape`	右クリックメニューを閉じる

Studio キャンバス操作ガイド ​

1. インターフェース概要 ​

Node Palette ノード分類 ​

2. 基本操作 ​

2.1 ノードの追加 ​

2.2 ノードの接続 ​

2.3 ノードの選択と削除 ​

2.4 ノードの複製 ​

2.5 Undo / Redo（元に戻す / やり直し） ​

2.6 Auto Layout 自動レイアウト ​

2.7 クイック保存 ​

2.8 右クリックメニュー ​

2.9 ワークフローのインポート ​

3. Properties Panel プロパティパネル ​

4. Chat Panel チャットパネル ​

4.1 Execute タブ ​

4.2 AI Build タブ ​

5. Workflow Settings ワークフロー設定 ​

変数 (Variables) ​

ミドルウェア (Middleware) ​

GuardRails — コンテンツセーフティガード ​

PII Masking — 個人情報保護 ​

その他のミドルウェア ​

Hooks イベントフック ​

6. Code Generation コード生成 ​

7. Export エクスポート ​

8. Save as Template テンプレートとして保存 ​

ショートカットキー一覧 ​