Skip to content

Agentic AI システムアーキテクチャ

本ドキュメントでは、Open WebUI + Agentic AI Server + MCPサーバー（ツール）の構成と、コンポーネント間の通信フローを説明する。

システム構成図

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '11px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 40, 'curve': 'basis'}}}%%
flowchart TB
    Browser["<b>🌐 ユーザーブラウザ</b>"]
    ALB["<b>ALB + ACM証明書</b><br/>SSL/TLS終端"]
    OpenWebUI["<b>Open WebUI :8080</b><br/>・チャットUI<br/>・ユーザー認証 Cognito OIDC<br/>・チャット履歴管理<br/>・モデル選択・設定"]
    RDS[("<b>RDS PostgreSQL</b><br/>・ユーザー情報<br/>・チャット履歴<br/>・設定データ")]
    Agentic["<b>Agentic AI Server :8000</b><br/>・OpenAI互換API<br/>・ReActエージェント(LangGraph)<br/>・MCPツール統合<br/>・M2M認証処理"]
    MCP["<b>MCPサーバー</b><br/>・ドキュメント検索<br/>・気象データ取得<br/>・その他ツール"]
    Claude["<b>☁️ Claude API</b><br/>・Claude sonnet<br/>・チャット応答生成<br/>・ツール呼び出し判断"]
    ES[("<b>Elasticsearch</b><br/>・ドキュメントストア<br/>・ベクトル/全文検索<br/>・ハイブリッド検索")]

    Browser -->|"HTTPS :443"| ALB
    ALB -->|"/*"| OpenWebUI
    OpenWebUI -->|"|:5432"| RDS
    OpenWebUI -->|"OpenAI互換API"| Agentic
    Agentic -->|"HTTP + Bearer Token"| MCP
    Agentic -->|"HTTPS"| Claude
    MCP -->|"|:9200"| ES

    style OpenWebUI fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style Agentic fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style MCP fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Claude fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style RDS fill:#e8f5e9,stroke:#2e7d32
    style ES fill:#e8f5e9,stroke:#2e7d32

補足

Open WebUIとAgentic AI Serverは同一ECSクラスター内で動作し、Service Connect経由で通信する。

  • Open WebUIは http://agentic:8000/v1 でAgenticにアクセスする
  • DNS解決はCloudMap（Service Discovery）が担当する
  • ALBを経由せず、内部ネットワークで直接通信する

セキュリティ・認証について

  • 外部からのアクセスはALB経由のみ許可される
  • ユーザー認証はCognito OIDCで行う
  • ALBはHTTPS（ACM証明書）でSSL/TLS終端を担当する
  • MCPサーバーは外部ツール接続を想定しており、Cognito M2Mトークン（Client Credentials）またはCognitoユーザー認証で接続する

コンポーネント詳細

1. Open WebUI

ユーザー向けのチャットインターフェースである。

機能

機能 説明
チャットUI Webベースのチャットインターフェース
ユーザー認証 Cognito OIDC経由のSSO
履歴管理 PostgreSQLにチャット履歴を保存する
モデル選択 Agenticサーバーから提供されるモデル一覧を表示する

接続先

  • Agentic AI Server: OpenAI互換API (http://agentic:8000/v1)
  • RDS PostgreSQL: ユーザーデータ・履歴保存

2. Agentic AI Server

AIエージェントのオーケストレーションを担当する。

機能

機能 説明
OpenAI互換API /v1/chat/completions, /v1/models を実装
ReActエージェント LangGraphベースの推論・ツール実行ループ
MCPツール統合 複数MCPサーバーからツールを集約する
M2M認証 Cognito Client Credentialsでトークンを取得する
ストリーミング SSE形式でリアルタイム応答する

SSEストリーミングについて

SSE (Server-Sent Events) は、サーバーからクライアントへの一方向リアルタイム通信を実現するHTTP標準技術である。 LLMがトークンを生成するたびにクライアントへ即座に送信し、ユーザーは回答の生成過程をリアルタイムで確認できる。WebSocketと異なり、通常のHTTP接続上で動作するため、プロキシやロードバランサーとの互換性が高い。

接続先

  • Anthropic API: Claude LLMへのリクエスト
  • MCPサーバー: ツール実行リクエスト

3. MCPサーバー

外部データソースへのアクセスを提供する。各種業務データやナレッジベースへの統一的なアクセス手段をLLMに提供し、AIが必要な情報を自律的に取得できるようにする。

提供ツール

ツール 説明
マニュアル等検索 技術文書・業務マニュアル・手順書の全文検索
事例検索（Karte） 過去の対応事例・ナレッジベースの検索
xROAD DB検索 道路関連データベースへのアクセス
気象データ取得 観測所情報・時系列気象データの取得

今後の拡張予定

  • 画像AI連携: 画像認識・解析AIをツールとして統合し、写真や図面からの情報抽出、過去事例の検索を可能にする。

接続先

  • Elasticsearch: ドキュメント・事例のRRFハイブリッド検索（全文検索・ベクトル検索）
  • xROAD DB
  • 気象データAPI: 観測所・観測時系列データ、統計値集約等

認証

Cognito M2M認証（Machine-to-Machine）を使用する。

M2M認証はOAuth 2.0のClient Credentials Grantフローを利用したサーバー間認証方式である。ユーザーの介在なしにサービス間で安全に認証を行うことができる。

認証フロー:

  1. Agentic AI ServerがCognitoに対してClient ID/Secretを送信
  2. Cognitoがアクセストークン（JWT）を発行
  3. Agentic AI ServerがMCPサーバーへのリクエストにBearer Tokenとして付加
  4. MCPサーバーがトークンを検証し、スコープに基づいてアクセスを許可

スコープ:

  • docsearch/read: ドキュメント閲覧権限
  • docsearch/search: 検索実行権限

通信フロー

チャットリクエストの流れ

1. ユーザー入力

ブラウザ → Open WebUI

ユーザーがチャット画面でメッセージを入力し送信する。

2. API呼び出し

Open WebUI → Agentic Server

POST /v1/chat/completions
{
  "model": "agentic-mcp",
  "messages": [{"role": "user", "content": "..."}],
  "stream": true
}

3. LLM推論

Agentic Server → Anthropic API

  • ユーザーメッセージ + ツール定義を送信
  • Claudeが応答またはツール呼び出し（tool_use）を返却

4. ツール実行（必要な場合）

Agentic Server → MCPサーバー

Claudeがツール呼び出しを要求した場合、Agentic ServerがMCPサーバーにリクエストを送信する。

  • M2Mトークンを付加（Bearer Token）
  • ツール名とパラメータを送信
  • 結果を受信

5. 最終応答生成

Agentic Server → Anthropic API

ツール結果をClaudeに渡し、最終回答を生成させる。ツールが不要な場合はこのステップをスキップする。

なお、ツール呼び出しと応答生成のループはLangGraphで制御しており、プロンプトで参考文献の出力形式や回答品質や特定タスクに関するガイドラインやガードレールを指定している。

6. ストリーミング応答

Agentic Server → Open WebUI → ブラウザ

  • SSE形式でトークンをチャンク送信
  • UI上でリアルタイム表示

シーケンス図

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '11px'}, 'sequence': {'actorMargin': 40, 'boxMargin': 5, 'mirrorActors': false}}}%%
sequenceDiagram
    participant Browser as ブラウザ
    participant WebUI as WebUI
    participant Agentic
    participant Anthropic
    participant MCP

    Browser->>WebUI: チャット
    WebUI->>Agentic: POST /v1/chat
    Agentic->>Anthropic: 推論要求
    Anthropic-->>Agentic: tool_use
    Agentic->>MCP: ツール実行
    MCP-->>Agentic: 結果返却
    Agentic->>Anthropic: 最終推論
    Anthropic-->>Agentic: 応答
    Agentic-->>WebUI: SSE
    WebUI-->>Browser: 表示更新

Appendix

以下参考情報

認証フロー

1. ユーザー認証（ブラウザ → Open WebUI）

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '11px'}, 'sequence': {'actorMargin': 40, 'boxMargin': 5, 'mirrorActors': false}}}%%
sequenceDiagram
    participant Browser as ブラウザ
    participant ALB
    participant Cognito
    participant WebUI as Open WebUI

    Browser->>ALB: アクセス
    ALB->>WebUI: リクエスト転送
    WebUI->>Cognito: OIDCリダイレクト
    Cognito->>Browser: ログインページ
    Browser->>Cognito: 認証情報入力
    Cognito->>WebUI: JWTトークン
    WebUI->>Browser: 認証完了

2. Open WebUI → Agentic AI Server（認証なし）

Open WebUI → Agentic AI Server (Service Connect経由)

  • 内部ネットワーク通信のため認証不要
  • Open WebUIは OPENAI_API_KEY=dummy を設定
  • Agenticサーバーはキーを検証しない
  • セキュリティはVPC/Security Groupで担保

理由:

  • 同一VPC内のECSタスク間通信
  • Security Groupで通信を制限（ECS SG同士のみ許可）
  • 外部からAgenticサーバーへの直接アクセス不可

3. M2M認証（Agentic → MCPサーバー）

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '11px'}, 'sequence': {'actorMargin': 40, 'boxMargin': 5, 'mirrorActors': false}}}%%
sequenceDiagram
    participant Agentic
    participant Cognito
    participant MCP as MCPサーバー

    Agentic->>Cognito: POST /oauth2/token<br/>grant_type=client_credentials
    Cognito-->>Agentic: access_token
    Agentic->>MCP: Authorization: Bearer {token}
    MCP-->>Agentic: レスポンス

認証情報の保存場所

認証情報 保存先 用途
Anthropic API Key Secrets Manager Claude API呼び出し
M2M Client ID/Secret Secrets Manager MCPサーバー認証
OAuth Client ID/Secret Secrets Manager Open WebUI OIDC
DATABASE_URL Secrets Manager PostgreSQL接続

APIエンドポイント一覧

Agentic AI Server

OpenAI互換API
エンドポイント メソッド 説明
/v1/chat/completions POST チャット応答（ストリーミング対応）
/v1/models GET 利用可能モデル一覧
内部API
エンドポイント メソッド 説明
/api/chat POST 非ストリーミングチャット
/api/chat/stream GET SSEストリーミングチャット
/api/planner/stream GET 多段思考エージェント
/api/tools GET 利用可能ツール一覧
/api/tools/settings POST ツール設定更新
/health GET ヘルスチェック

MCPサーバー

エンドポイント メソッド 説明
/mcp POST MCP JSONRPCエンドポイント
/health GET ヘルスチェック

データフロー

リクエスト/レスポンス形式

Open WebUI → Agentic（チャットリクエスト）
{
  "model": "agentic-mcp",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "東京の天気を教えて"}
  ],
  "stream": true
}
Agentic → Anthropic（ツール定義付きリクエスト）
{
  "model": "claude-sonnet-4-5",
  "messages": [...],
  "tools": [
    {
      "name": "get_weather_timeseries",
      "description": "指定した観測所の気象データを取得",
      "input_schema": {
        "type": "object",
        "properties": {
          "station_id": {"type": "string"},
          "start_date": {"type": "string"},
          "end_date": {"type": "string"}
        }
      }
    }
  ]
}
Agentic → MCPサーバー（ツール実行）
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_weather_timeseries",
    "arguments": {
      "station_id": "47662",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  }
}
ストリーミングレスポンス（SSE形式）
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"東京の"}}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"天気は"}}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"晴れです。"}}]}

data: [DONE]

エラーハンドリング

HTTPステータスコード

コード 状況 対応
400 リクエスト不正 パラメータ確認
401 認証エラー API Key/Token確認
503 Anthropic過負荷 リトライ（指数バックオフ）
504 タイムアウト 再試行

フォールバック動作

状況 動作
MCPサーバー接続失敗 ツールなしで継続（LLMのみで応答）
M2Mトークン取得失敗 MCPサーバーへのリクエストをスキップ
Anthropic 529エラー 最大3回リトライ後にエラー返却

環境変数

Agentic AI Server

変数名 説明 例
ANTHROPIC_API_KEY Claude API Key sk-ant-xxx
ANTHROPIC_MODEL 使用モデル claude-sonnet-4-5
MCP_MET_URL MCPサーバーURL https://xxx.com/mcp
MCP_TRANSPORT MCPトランスポート streamable_http
M2M_CLIENT_ID M2M Client ID xxx
M2M_CLIENT_SECRET M2M Client Secret xxx
M2M_COGNITO_DOMAIN Cognitoドメイン xxx.auth.ap-northeast-1.amazoncognito.com
M2M_SCOPES M2Mスコープ docsearch/read docsearch/search

Open WebUI

変数名 説明 例
WEBUI_URL 公開URL https://xxx.com
OPENAI_API_BASE_URL Agentic接続先 http://agentic:8000/v1
DATABASE_URL PostgreSQL接続 postgresql://...
OAUTH_CLIENT_ID Cognito Client ID xxx
OAUTH_CLIENT_SECRET Cognito Client Secret xxx
OPENID_PROVIDER_URL OIDC設定URL https://cognito-idp...