15. 業務に組み込む¶

15.1. エージェントの呼び出し方¶

エージェントをIM-LogicDesignerやIM-BPMから呼び出すには、エージェント定義の用途で「ロジックフロータスク」または「BPMタスク」を ON にします。呼び出し元の画面でエージェントを選ぶときは、その用途を ON にしたエージェントだけが候補に表示されます。

ただし、用途は候補を絞り込むための設定であり、実行時のアクセス制御ではありません。例えばIM-LogicDesignerの「エージェント実行」タスクでは、用途を OFF にしても、すでにタスクに設定したエージェントの実行は止まりません。誰がエージェントを実行できるかは、呼び出し元のロジックフローやワークフローの側で制御します。

同期実行には、呼び出し元のタイムアウトが影響します。エージェントの実行に時間がかかる場合、呼び出し元のタイムアウト設定によっては、応答が返る前に処理が打ち切られることがあります。

エージェントを直接呼び出す公開 REST API は提供されません。外部システムから呼び出す必要がある場合は、IM-LogicDesignerを経由します。「エージェント実行」タスク（「IM-LogicDesigner の「エージェント実行」タスク」）を含むロジックフローを作成し、そのロジックフローを外部へ公開して呼び出します。

15.2. IM-LogicDesigner の「エージェント実行」タスク¶

「エージェント実行」タスクは、IM-LogicDesigner のパレットのカテゴリ「IM-Copilot」から配置します。このカテゴリには、既存の IM-Copilot タスク（チャット、画像生成、ベクトルDB 操作など）も同居します。

図：パレットの「エージェント実行」タスクと、配置後のキャンバス上のフロー。

エージェントID と、呼び出すバージョンは、タスクのプロパティの「タスク固有設定」で指定します（図の赤枠）。マッピング設定で指定する項目ではありません。エージェントID の検索アイコンから「エージェントを選択」画面を開き、エージェントと、使用するバージョン（「常に最新のバージョンを利用する」または特定のバージョン番号）を選びます。この画面には、用途「ロジックフロータスク」が ON で、公開中のエージェント・バージョンだけが表示されます。選んだバージョンが後から非公開になった場合は実行時にエラーになり、「常に最新のバージョンを利用する」を選んだ場合は、公開中のバージョンのうち最大の番号が使われます。

図：タスクのプロパティ。「タスク固有設定」（赤枠）で、エージェントID とバージョン（「常に最新」）を指定する。

入力には、prompts、inputParameters、session があります。prompts の各要素には、text・imageUrl・image のうち、いずれか 1 つを指定します。prompts に要素を 1 つも指定しない場合はエラーが発生します。inputParameters は、エージェント定義に入力スキーマが設定されている場合にだけ生成されます。

図：マッピング設定画面。prompts や inputParameters に、開始タスクの入力や定数をマッピングする。

出力には、result と session があります。エージェントの応答は result に入ります。エージェント定義で構造化出力を設定している場合は、出力パラメータの値が result の outputParameters に入ります。

入力・出力の各項目の型や詳細は、「IM-LogicDesigner仕様書」の「エージェント実行」を参照してください。

図：フロー定義のデバッグ実行結果。「フロー定義の変数情報」の「出力」に、構造化出力のスキーマに沿った outputParameters の値が展開される。

15.3. IM-BPM から呼ぶ¶

用途で「BPMタスク」を選んだエージェントは、IM-BPM のプロセスから呼び出せます。IM-BPM が未導入の環境では、この用途そのものが選択肢に表示されません。

IM-BPM のプロセスデザイナには、専用の「AccelAgentタスク」があります。タスクには、連携先のエージェントを指定する連携ID、利用するバージョン（常に最新を使用するか、バージョン番号を指定するか。EL 式での動的指定も可能）、エージェントへ渡す入力データを設定します。実行結果を後続のタスクで使う場合は「結果変数を格納する」を有効にし、結果変数名（例: result）を指定すると、以降のタスクから ${result}のような EL 式（「IM-BPM 仕様書」の「EL式」）で参照できます。

入力データのうち、名前を message にした項目は、エージェントへのメッセージとして渡されます。それ以外の項目は、エージェント定義のインプットパラメータとして渡されます。message を設定しない場合は、空のメッセージで実行されます。

バージョン番号を指定した場合も、そのバージョンが公開されていなければエラーが発生します。結果変数には、エージェント定義で構造化出力を設定している場合はその値が、設定していない場合は応答の本文が格納されます。

エージェントの実行がエラーやガードレールによる遮断で終わった場合は、プロセスの実行がエラーで終了します。また、IM-LogicDesignerから呼び出す場合と同じく、実行種別は「本番」として記録され、AI モデルの呼び出しによる課金やツールの実行も実際に行われます。

15.4. Java から呼ぶ¶

Java のプログラムからも、エージェント定義を指定してエージェントを呼び出せます。AgentManagementServiceFactoryから取得した AgentManagementService でエージェントを読み込み、実行します。

getAgent メソッドは、バージョンの公開状態を問わずにエージェントを読み込みます。IM-LogicDesignerやIM-BPMのタスクと同じく公開中のバージョンだけを実行したい場合は、resolvePublishedVersionメソッドで解決したバージョン番号を指定して読み込みます。

クラスやメソッドの詳細は、「jp.co.intra_mart.foundation.copilot.agent パッケージの API ドキュメント」を参照してください。

15.5. バージョンの更新と進行中案件¶

特定のバージョン番号を指定して呼び出している箇所がある状態で、そのバージョンを非公開にすると、呼び出しは失敗します。IM-LogicDesignerの「エージェント実行」タスクとIM-BPMの「AccelAgentタスク」は、どちらもタスクを実行する時点でバージョンの公開状態を確認するためです。IM-LogicDesignerではフローの実行が、IM-BPMではプロセスの実行がエラーで終了します。

「常に最新のバージョンを利用する」を選んだ呼び出しは、実行する時点で公開中のバージョンのうち最も大きい番号を使います。そのため、公開中のバージョンが 1 つでも残っていれば失敗しません。ただし、新しいバージョンを公開すると、すべての呼び出し元が次の実行から新しいバージョンを使います。インプットパラメータや構造化出力の項目を変えた場合は、後続の処理が想定どおりに動くか、公開前に確認します。

バージョン番号を指定して呼び出しているエージェントを新しいバージョンに切り替える場合は、次の順に作業します。

1. 新しいバージョンを公開します。古いバージョンは、この時点では非公開にしません。
2. 古いバージョンの番号を指定しているIM-LogicDesignerのフローとIM-BPMのプロセスを洗い出し、指定を新しいバージョンに変更します。
3. 変更した呼び出し元を実行し、新しいバージョンで想定どおりに動くことを確認します。
4. 古いバージョンを呼び出す処理が残っていないことを確かめてから、古いバージョンを非公開にします。

IM-BPMでは、進行中の案件にも注意します。AccelAgentタスクのバージョン指定はプロセス定義に含まれるため、案件がどのバージョンを呼び出すかは、その案件が使っているプロセス定義で決まります。古いバージョンを指定したプロセス定義で進んでいる案件が残っている間は、古いバージョンを公開したままにしておき、それらの案件がAccelAgentタスクを通過してから非公開にします。

エージェント定義をインポートすると、インポート先で公開中だったバージョンが非公開に変わることがあります（警告は表示されます）。稼働中の環境へ取り込む際は、インポート後に公開状態を確認する作業とセットで行います（「インポートで何が起きるか」）。