Amazon Connect Customer AIエージェントのエージェントアシスタンスでは、ログインユーザーにもツール権限が必要です

困っていること

Amazon Connect Customer AIエージェントのエージェントアシスタンスで、オーケストレーションタイプの AIエージェントから Flow module tool（以降、フローモジュールツール）を呼び出す構成を検証しています。

AIエージェントに関連付けたセキュリティプロファイルでは、対象のフローモジュールツールへのアクセスを許可しています。

しかし、エージェントワークスペースから AIエージェントにフローモジュールツールを実行させると失敗し、フローモジュールや後続の AWS Lambda 関数が実行されませんでした。

エージェントワークスペースからフローモジュールツールを実行した際に失敗した画面

AIエージェントログの一部は以下です。

{
  "status": "error",
  "message": "MCP tool execution failed: MCP error -32001: Tool is not allowed"
}

AIエージェント側にツールへのアクセス権限を設定するだけでは不十分なのでしょうか。

回答

結論として、エージェント支援で AIエージェントを利用する場合、AIエージェントだけでなく、エージェントワークスペースのログインユーザーに割り当てられたセキュリティプロファイルにも、対象ツールへのアクセス権限が必要です。

本記事では、エージェントワークスペースにログインしてエージェント支援を利用するユーザーを「ログインユーザー」と表記します。

今回の構成では、次の両方にフローモジュールツールへのアクセス権限を設定する必要があります。

AIエージェント側にのみ権限があり、ログインユーザー側に権限がない場合、今回の検証では Tool is not allowed が発生しました。

ログインユーザーにも権限が必要な理由

エージェント支援の AIエージェントは、エージェントワークスペースにログインしているユーザーのセッションコンテキスト内で動作します。

そのため、ツール呼び出しは AIエージェントの権限だけでなく、ログインユーザーに割り当てられたセキュリティプロファイルの権限も組み合わせて認可されます。

AIエージェント側にツールへのアクセス権限があっても、ログインユーザー側に同じ権限がなければ、対象ツールを実行できません。

公式ドキュメントでも、エージェント支援で AIエージェントを使用する場合、エージェントワークスペースを利用するユーザーのセキュリティプロファイルに、AIエージェントで設定したツールと同じアクセス許可が必要であることが説明されています。

https://docs.aws.amazon.com/ja_jp/connect/latest/adminguide/ai-agent-security-profile-permissions.html#tool-level-permissions

つまり、次の設定はそれぞれ別に確認する必要があります。

• AIエージェントにフローモジュールツールを追加する
• AIエージェントに関連付けたセキュリティプロファイルで、対象ツールへのアクセスを許可する
• ログインユーザーに割り当てられたセキュリティプロファイルで、同じツールへのアクセスを許可する

AIエージェントにツールを追加しただけでは、エージェント支援からツールを実行するための権限設定は完了しません。

セキュリティプロファイルの設定

エージェント支援からフローモジュールツールを呼び出す場合は、AIエージェントとログインユーザーの両方についてセキュリティプロファイルを確認します。

AIエージェント側のセキュリティプロファイル

AIエージェントに関連付けたセキュリティプロファイルで、呼び出すフローモジュールツールへのアクセスを許可します。

AIエージェントの設定画面でツールを追加する設定と、セキュリティプロファイルによるアクセス許可は別の設定です。

そのため、AIエージェントにツールが追加されていることに加えて、関連付けたセキュリティプロファイルで対象ツールへのアクセスが許可されていることを確認します。

ログインユーザー側のセキュリティプロファイル

エージェントワークスペースのログインユーザーに割り当てられたセキュリティプロファイルでも、AIエージェントが呼び出すフローモジュールツールへのアクセスを許可します。

今回の検証では、ログインユーザーに割り当てられたセキュリティプロファイルを開き、対象のフローモジュールツールへのアクセスを許可しました。

ログインユーザーに割り当てられたセキュリティプロファイルで、対象のフローモジュールツールへのアクセスを許可した画面

複数のセキュリティプロファイルをログインユーザーに割り当てている場合は、そのユーザーに適用される設定全体を確認してください。

また、セキュリティプロファイルでは、AIエージェントが実際に呼び出すフローモジュールツールがアクセス許可の対象になっていることを確認します。

動作確認

ログインユーザーに割り当てられたセキュリティプロファイルで、対象のフローモジュールツールへのアクセスを許可した後、エージェントワークスペースから再度動作を確認しました。

今回の検証では、ログインユーザー側の権限を修正することで、次のエラーは解消しました。

MCP tool execution failed: MCP error -32001: Tool is not allowed

ただし、権限を修正した後は、別のエラーが発生しました。

MCP tool execution failed: Failed to start flow module execution.

Tool is not allowed からエラー内容が変わったため、ログインユーザー側の権限不足については解消し、ツールの認可後に別の問題が発生していると切り分けました。

今回の検証では、その後フローモジュールの設定を修正したところ、フローモジュールツールの実行に成功しました。

ログインユーザーの権限とフローモジュールの設定を修正した後、ツールの実行に成功した画面

今回確認した2つのエラーは、次のように分けて切り分ける必要があります。

今回の検証で確認したエラーの変化

Tool is not allowed

当初、フローモジュールツールの実行時に以下のエラーが発生しました。

MCP tool execution failed: MCP error -32001: Tool is not allowed

今回の検証では、ログインユーザーに割り当てられたセキュリティプロファイルで、対象のフローモジュールツールへのアクセスが許可されていないことが原因でした。

次の設定を確認し、ログインユーザー側のセキュリティプロファイルに不足していた権限を追加したところ、Tool is not allowed は解消しました。

• AIエージェントに対象のフローモジュールツールが追加されている
• AIエージェントに関連付けたセキュリティプロファイルで、対象ツールへのアクセスが許可されている
• ログインユーザーに割り当てられたセキュリティプロファイルで、同じツールへのアクセスが許可されている

このとき、フローモジュールや後続の Lambda 関数は実行されず、Lambda 関数のログも出力されませんでした。

おっしゃるとおりです。この記事の主題はログインユーザーのツール権限であり、Failed to start flow module execution は補足的な事象です。

InvokeLambdaFunction や EndFlowModuleExecution、出力スキーマの詳細まで説明すると、記事の主題が分散します。以下のように、権限修正後に別のエラーが発生し、フローモジュールの出力設定を修正して解消したことだけを書くのがよいです。

Failed to start flow module execution

ログインユーザー側の権限を修正した後は、以下のエラーが発生しました。

MCP tool execution failed: Failed to start flow module execution.

今回の検証では、フローモジュールが返す結果の形式と、フローモジュールに定義した出力スキーマが一致していないことが原因でした。出力スキーマに合わせて結果を返すように修正したところ、フローモジュールツールの実行に成功しました。

今回確認した2つのエラーと対応結果は、以下のとおりです。

Tool is not allowed と Failed to start flow module execution は、今回の検証では異なる原因で発生しました。前者はログインユーザー側の権限不足、後者はフローモジュールの出力設定の不一致が原因でした。

まとめ

Amazon Connect Customer AIエージェントをエージェントアシスタンスで利用する場合、フローモジュールツールへのアクセス権限は、AIエージェントだけでなく、エージェントワークスペースのログインユーザーにも必要です。

Tool is not allowed が発生した場合は、ログインユーザーに割り当てられたセキュリティプロファイルで、対象ツールへのアクセスが許可されているか確認してください。

今回の検証では、権限の修正後に発生した Failed to start flow module execution は、フローモジュールが返す結果の形式と出力スキーマを一致させることで解消しました。2つのエラーは原因が異なるため、分けて確認する必要があります。