メインコンテンツまでスキップ

AI エージェント

AI エージェントは、複数のステップで動作するアシスタントです。会話を読み取り、計画を立て、ツール（AI ツール、MCP ツール、ナレッジベース検索）を呼び出し、その結果を確認して、答えが出るまで再びモデルを呼び出します。AI チャット補完を作成ノードはモデルを 1 回呼び出して返信するだけですが、AI エージェントノードは、設定した上限の範囲内で、モデル呼び出しとツール呼び出しを何度も繰り返してから回答できます。

リクエストに複数のステップが必要な場合にエージェントを使います。たとえば「お客様の注文を探し、配送状況を確認して、新しい日付を提案する」といった場合です。手順とナレッジベースから直接回答するだけなら、AI ノードのほうがシンプルで低コストです。

構成要素​

要素内容設定場所
AI ハーネスエージェントのループを実行するエンジン。MonoChat 独自のもの、エージェント SDK、またはホステッドのエージェントサービスのいずれかです。設定 › オートメーション › AIハーネス
モデルエージェントが思考に使う AI モデル。メインモデル、任意のフォールバックモデル、任意の高速モデルがあります。ホステッドハーネスでは、代わりにそのプロバイダー独自のモデルが使われます。AI エージェントノード
ツールAIスコープ、AIツール関数、MCP ツール。AI エージェントノード
実行予算実行ごとの、モデル呼び出し、ツール呼び出し、トークン、所要時間、リトライ回数の上限。AI エージェントノード
実行エージェントの 1 回の実行。すべての実行は AI エージェントの実行履歴に記録されます。ノードまたは API によって作成されます

AIハーネス​

設定 › オートメーション › AIハーネスには、エージェントを実行できるハーネスが一覧表示されます。MonoChat がすべてのワークスペースに提供するものと、ご自身の認証情報で追加したものです。

ハーネス実行場所使用するモデル追加するのは
MonoChat NativeMonoChat 内お客様の AI モデルMonoChat
OpenAI Agents SDKMonoChat 内お客様の AI モデルMonoChat
Claude Agent SDKMonoChat のエージェントランナー上お客様の AI モデルMonoChat
piMonoChat のエージェントランナー上お客様の AI モデルMonoChat
OpenAI Agents APIOpenAI のクラウドハーネスで許可されたモデルお客様（OpenAI の API キーを使用。MonoChat が提供する場合もあります）
Claude Managed AgentsAnthropic のクラウドハーネスで許可されたモデルお客様（Anthropic の API キーを使用。MonoChat が提供する場合もあります）
カスタムエンドポイントお客様自身のサーバーお客様の AI モデル（任意）お客様（エンドポイントとシークレットを使用）

MonoChat 上で実行されるハーネスは MonoChat が提供します。ワークスペースで追加できるのは、独自の認証情報を使うハーネスのみです。Claude Agent SDK と pi には MonoChat のエージェントランナーが必要です。これが設定されていない環境でこれらを使って実行すると、「This harness is not available on this server.」で失敗します。

どのハーネスでも、制御は MonoChat が握っています。お客様の AI モデルを使うハーネスのモデル呼び出しはすべて MonoChat を経由する（そのため課金と予算が適用される）こと、ツール呼び出しではワークスペース内の関数、MCP ツール、AIスコープが実行されること、そして予算がすべてのハーネスで適用されることです。

ハーネスを追加する​

  1. 設定 › オートメーション › AIハーネスに移動し、+（作成）をクリックします。
  2. 名前を入力し、必要に応じて説明も入力します。
  3. ハーネスを選択します。各選択肢には実行場所が表示されます。
  4. 認証情報に、ハーネスが必要とする情報を入力します。
    • OpenAI Agents API、Claude Managed Agents: APIキー。
    • カスタムエンドポイント: エンドポイントとAPIキー。
  5. ホステッドハーネスの場合は、許可されるモデルを入力します。プロバイダーのモデル名（たとえば OpenAI または Anthropic のモデル ID）を入力してください。モデルを追加で最大 10 個のモデルを追加できます。このハーネスのエージェントは、この一覧からのみ選択できます。
  6. 保存をクリックします。

ハーネスを編集する場合、ハーネスの種類は変更できません。また、キーのフィールドには**API キー（保存済みのキーを維持する場合は空のままにしてください）**と表示されます。

Claude Managed Agents

この種類のハーネスが初めて使われるとき、MonoChat はその Anthropic アカウントにエージェントと環境を 1 つずつ作成し、以降はそれらを再利用します。

カスタムエンドポイント​

カスタムエンドポイントのハーネスは、実行をお客様自身のサービス（たとえばセルフホストのエージェント）に送信します。実行ごとに、MonoChat は Authorization: Bearer <API Key> を付けて <Endpoint>/runs に POST を送信します。本文には、実行 ID、手順、入力、会話のメッセージ、予算、モデルのエイリアス（agent-main、agent-fallback、agent-fast）、そしてこの実行用のトークンが付いた 3 つの URL が含まれます。

  • ノードの AI モデルを呼び出して予算を適用する、モデルゲートウェイ（OpenAI 互換の …/v1 と Anthropic 互換のベース URL）。
  • 実行のツールを公開する MCP サーバー。
  • お客様のサービスが結果を報告するイベント URL（result 付きの completed、または error 付きの failed）。

実行のトークンは、実行が終了すると無効になります。

AI エージェントノード​

フローデザイナーのハイブリッドノードにある AI エージェントノードを使って、フローにエージェントを追加します。ノードの追加と接続の方法については、フローをご覧ください。

フィールド​

セクションフィールド説明
名前キャンバスに表示されるノード名。
AI ハーネス必須。エージェントを実行するハーネス。
手順エージェントのシステム指示。役割、トーン、ルール、してよいこと・いけないこと。
タスク（エージェントの指示に追加されます。タグを使用できます）このノードでエージェントに依頼する内容。手順の後に追加され、AI ノードのプロンプトと同じタグを使えます。たとえば、お客様のデータを含めることができます。
モデルメインモデルエージェントが使うモデル。カスタムエンドポイント以外のすべてのハーネスで必須です。
フォールバックモデル（ソフトリミット後）モデル呼び出しがソフトリミットに達したときにエージェントが切り替えるモデル。通常は、より安価または高速なモデルです。
高速モデル（軽量なバックグラウンドタスク用）ハーネスが軽量なバックグラウンド呼び出しに使えるモデル。
モデル（ハーネスで許可されたモデルのいずれか）ホステッドハーネスの場合、上の 3 つのフィールドの代わりに表示されます。
エージェントの会話会話既存のエージェントセッションを継続（デフォルト）または新しいエージェントセッションを開始。エージェントセッションをご覧ください。
タスクキー（タスクごとに別のエージェント会話）任意。同じ会話内で、キーごとに別のエージェントセッションを保持します。たとえば booking と support です。
メッセージ履歴の上限エージェントが受け取る会話メッセージの数。
音声認識AIモデル文字起こし機能を持つモデル。会話内の音声メッセージが、テキストとしてエージェントに渡されます。
ツール設定AIスコープエージェントが検索できるナレッジベース。ナレッジベース検索ツールとしてエージェントに提供されます。
AIツールエージェントが呼び出せる、AIツールタイプの関数。
AI MCP クライアントコンテンツツールを設定MCP ツールを追加するドロワーを開きます。MCP クライアントをご覧ください。
メッセージ中間メッセージをお客様に転送デフォルトではオフです。オンにすると、エージェントが作業中に書いたもの（たとえば「ご注文を確認しますね」）がお客様に送信されます。オフの場合は、チームだけが見られるウィスパーメッセージとして会話に追加されます。
回答を送信デフォルトではオンです。エージェントの最終回答をお客様に送信します。回答をフロー内だけで使う場合は、オフにします。
実行予算最大モデル呼び出し数デフォルトは 4。
ソフトリミット: モデル呼び出し任意。このモデル呼び出し回数に達すると、エージェントはフォールバックモデルに切り替わります。最大モデル呼び出し数より小さい値にする必要があり、フォールバックモデルも必要です。
最大ツール呼び出し数デフォルトは 6。0 の場合、エージェントがツールを呼び出そうとした時点で、実行は予算超過として終了します。
最大合計トークン数デフォルトは 20000。実行内のすべてのモデル呼び出しの入力トークンと出力トークンの合計。
最大実行時間（秒）デフォルトは 30。
最大リトライ回数デフォルトは 2。失敗したモデル呼び出しを再試行する回数。
ヒント

変わらないルールは手順に、このステップ固有の仕事はタスクに書きましょう。そうすれば、フロー内の複数の AI エージェントノードで同じ手順を共有し、タスクだけを変えることができます。

警告

ホステッドハーネスはフォールバックモデルに切り替えられないため、ソフトリミットをサポートしていません。ホステッドハーネスでは、ソフトリミット: モデル呼び出しを空のままにしてください。

フローがノードに到達したときの動作​

  1. MonoChat が残高とノードの設定を確認し、実行を開始します。実行は待機中になり、その後実行中になります。フローインスタンスはノードで待機します。
  2. エージェントは手順とタスクを受け取ります。フローが会話に属している場合は、メッセージ履歴の上限までの会話メッセージも受け取ります（音声メッセージは文字起こしされます）。
  3. エージェントは、答えが出るか上限に達するまで、モデルとツールを呼び出します。ツール呼び出しの合間にエージェントが書いたテキストは、中間メッセージとして処理されます。
  4. 実行が終了したとき:
    • 完了し、回答を送信がオンの場合、回答がお客様に送信されます。長い回答は、チャネルの上限（WhatsApp では 4096 文字）を超える場合、複数のメッセージに分割されます。
    • それ以外の終了の場合は、「AI agent run ended: status. error」というウィスパーメッセージが、チーム向けに会話に追加されます。
  5. フローは、実行の終了結果に対応する出力から続行されます。

同じエージェントセッションの実行は、順番に 1 つずつ処理されます。

出力​

出力条件
完了エージェントが回答を出して終了した。
予算超過実行が最大モデル呼び出し数、最大ツール呼び出し数、または最大合計トークン数を使い切った。
タイムアウト実行が**最大実行時間（秒）**に達した。
ヘイト、ジェイルブレイク、自傷行為、性的、暴力モデルプロバイダーのコンテンツフィルターが、このカテゴリーで実行を停止した。これらは AI ノードと同じ出力です。
失敗時その他の理由で実行が失敗した、またはキャンセルされた。これらの出力が追加される前に保存されたノードでは、コンテンツフィルターによる停止もここに入ります。そのようなノードは、開いて保存し直すと新しい出力が追加されます。

少なくとも完了と失敗時は接続してください。よくあるパターンとして、予算超過、タイムアウト、失敗時を会話を割り当てるノードに接続し、チームメンバーが対応を引き継ぐようにします。

エージェントセッション​

エージェントセッションは、実行をまたいだエージェントの記憶です。MonoChat は、会話、ハーネス、タスクキーごとに、アクティブなエージェントセッションを 1 つ保持します。

  • 既存のエージェントセッションを継続すると、それを再利用するため、エージェントは前回の続きから作業できます。ホステッドハーネスでは、プロバイダー側のセッションも継続されます。
  • 新しいエージェントセッションを開始すると、アクティブなセッションを閉じて新たに始めます。たとえば、新しいトピックの開始時に使います。
  • タスクキーを使うと、同じ会話内で独立したセッションを並行して保持できます。

課金​

  • MonoChat が提供する AI モデルでのモデル呼び出しは、通常どおり残高から課金されます。お客様自身のモデルでの呼び出しは、プロバイダーから請求されます。
  • MonoChat が提供するハーネスは、実行ごと、分ごと、ツール呼び出しごとの独自の料金を追加する場合があります。ホステッドハーネスの場合は、そのプロバイダーが報告するトークンも対象です。これらはトランザクションに、AI エージェントの実行、AI エージェントの稼働時間、AI エージェントのツール呼び出し、および AI トークンのカテゴリーとして表示されます。
  • ご自身の認証情報で追加したハーネスには MonoChat の料金はかかりません。そのプロバイダーから請求されます。
  • 残高が不足している場合、実行は開始されません。

AI エージェントの実行が終了しましたイベント​

AI エージェントの実行が終了しましたはイベントノードです。お客様に紐づく実行が終了したときに発火します。実行がフローから開始された場合でも、セッション付きの API から開始された場合でも同様です。他のイベントノードと同様に、任意の条件とタイムアウトの設定があります。エージェントの実行後に別のフローを開始したいとき、たとえば結果を記録したりチームに通知したりするときに使います。

コードからエージェントを開始する​

カスタム関数や API クライアントは、次のメソッドでエージェントを実行できます（権限: オートメーション内の AI エージェント実行の開始 / 閲覧 / キャンセル）。

メソッド動作
business.tenants.automation.ai.aiAgentRuns.create実行を開始します。aiAgentRunId と aiAgentSessionId を返します。
business.tenants.automation.ai.aiAgentRuns.show実行（_id）を、ステータス、使用量、ステップ、結果とともに返します。
business.tenants.automation.ai.aiAgentRuns.cancel待機中または実行中の実行（_id）をキャンセルします。

create は、aiHarnessClientId、input（タスク）を受け取ります。任意で sessionId（会話内で作業する場合）、aiAgentSessionId、taskKey、isNewSession を指定でき、ノードと同じ設定を持つ options も指定できます。options には、instructions、aiModelClientId、fallbackAiModelClientId、fastAiModelClientId、harnessModel、toolCustomFunctionIds、aiScopeIds、aiMcpClientDatas、messageHistoryLimit、speechToTextAiModelClientId、forwardIntermediateMessages、willSendAnswer、そして必須の budget があります。API 経由の場合、forwardIntermediateMessages と willSendAnswer のデフォルトは false です。

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

実行は非同期です。結果は後から show で読み取るか、AI エージェントの実行が終了しましたイベントで受け取ります。sessionId を指定しない場合、前回の呼び出しが返した aiAgentSessionId を渡さない限り、呼び出しのたびに新しいエージェントセッションが始まります。渡した場合、エージェントはそのエージェントセッションの過去の完了済みの実行を履歴として参照します。関数からメソッドを呼び出す方法については、メソッドをご覧ください。

権限​

権限できること
オートメーション内の AI ハーネスの閲覧 / 作成 / 更新 / 削除AIハーネスの管理
オートメーション内の AI エージェント実行の閲覧AI エージェントの実行履歴の表示
オートメーション内の AI エージェント実行の開始aiAgentRuns.create の呼び出し
オートメーション内の AI エージェント実行のキャンセルaiAgentRuns.cancel の呼び出し

ロールをご覧ください。