smolagentsとInterSystems IRIS（SQL、RAG、およびInteroperability）を使用してカスタマーサポートAIエージェントをビルドする

カスタマーサポートの質問は、構造化データ（オーダー、製品 🗃️）、非構造化知識（ドキュメント/よくある質問 📚）、およびライブストリーム（出荷更新 🚚）と多岐にわたります。 この投稿では、以下を使用して、3つすべてに対応するコンパクトなAIエージェントを作成します。

• 🧠 Python + smolagentsは、エージェントの「頭脳」を構成します
• 🧰 SQL、ベクトル検索（RAG）、およびInteroperabilityのためのInterSystems IRIS（モック配送状況API）

⚡ 要点まとめ（サクッと読める）

• InterSystems IRIS上でツール（モック配送APIのためのSQL、ベクトル検索/RAG、Interoperability）を統合するPython + smolagentsで実用的なAIカスタマーサポートエージェントをビルドします。
• テーブル、ドキュメント、およびInteroperability（相互運用性）呼び出しを組み合わせて、実際の質問（例：「注文番号#1001は配達されましたか？」 「返品可能期間は？」）に回答します。
• DockerでIRISを起動し、スキーマとサンプルデータを読み込みます。RAG用のドキュメントを埋め込み、ツール（SQL/RAG/API）を登録し、CLIまたはGradio UI経由でエージェントを実行します。

---

🧭 ビルド内容

AIカスタマーサポートエージェントは次を行えます。

• 🔎 SQL経由で構造化データ（顧客、注文、製品、出荷）をクエリする
• 📚 IRISベクトル検索上のRAG経由で非構造化知識（よくある質問とドキュメント）を取得する
• 🔌 IRISのInteroperability機能を使って（モックの）配送APIを呼び出し、Visual Traceで全ての呼び出しを確認する

アーキテクチャ（一目でわかる）

User ➜ Agent (smolagents CodeAgent)
               ├─ SQL Tool ➜ IRIS tables
               ├─ RAG Tool ➜ IRIS Vector Search (embeddings + chunks)
               └─ Shipping Tool ➜ IRIS Interoperability (mock shipping) ➜ Visual Trace

smolagentsは初めてですか？ Hugging Faceによる小さいエージェントフレームワークで、モデルが計画してあなたのツールを使用します。他の代替フレームワークにLangGraphとLlamaIndexがあります。

---

🧱 前提条件

• 🐍 Python 3.9以上
• 🐳 Docker（コンテナでIRISを実行するため）
• 🧑‍💻 VS Code（コードを確認するのに便利）
• 🔑 OpenAI APIキー（ LLMと埋め込み表現用。Ollamaを使用してローカルで実行することも可能）

---

1) 🧩 クローンとPythonを設定する

git clone https://github.com/intersystems-ib/customer-support-agent-demo
cd customer-support-agent-demo

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows (PowerShell)
# .venv\Scripts\Activate.ps1

pip install -r requirements.txt
cp .env.example .env   # add your OpenAI key

---

2) 🐳 InterSystems IRIS（Docker）を起動する

docker compose build
docker compose up -d

Management Portalを開きます（このデモでは http://localhost:52773）

---

3) 🗃️ 構造化データをロードする（SQL）

SQL Explorer（ポータル）またはお気に入りのSQLクライアントで次を実行します。

LOAD SQL FROM FILE '/app/iris/sql/schema.sql' DIALECT 'IRIS' DELIMITER ';';
LOAD SQL FROM FILE '/app/iris/sql/load_data.sql' DIALECT 'IRIS' DELIMITER ';';

これはたった今ロードしたスキーマです。

いくつかクエリを実行して、データの内容を把握します。 エージェントはこのデータを使用して、質問に対応します。

-- List customers
SELECT * FROM Agent_Data.Customers;

-- Orders for a given customer
SELECT o.OrderID, o.OrderDate, o.Status, p.Name AS Product
FROM Agent_Data.Orders o
JOIN Agent_Data.Products p ON o.ProductID = p.ProductID
WHERE o.CustomerID = 1;

-- Shipment info for an order
SELECT * FROM Agent_Data.Shipments WHERE OrderID = 1001;

✅ 行が表示される場合、構造化データの準備は完了しています。

---

4) 📚 ベクトル検索（RAG）で非構造化知識を追加する

埋め込み表現の構成を作成します（以下の例は、OpenAI埋め込みモデルを使用しています。お好みで調整してください）。

INSERT INTO %Embedding.Config
  (Name, Configuration, EmbeddingClass, VectorLength, Description)
VALUES
  ('my-openai-config',
   '{"apiKey":"YOUR_OPENAI_KEY","sslConfig":"llm_ssl","modelName":"text-embedding-3-small"}',
   '%Embedding.OpenAI',
   1536,
   'a small embedding model provided by OpenAI');

正確な手順とオプションが必要ですか？ ドキュメントを確認してください

その後、サンプルのコンテンツを埋め込みます。

python scripts/embed_sql.py

埋め込み表現がすでにテーブルに存在することを確認します。

SELECT COUNT(*) AS ProductChunks FROM Agent_Data.Products;
SELECT COUNT(*) AS DocChunks     FROM Agent_Data.DocChunks;

🔎 ボーナス：EMBEDDING() を使用してSQLから直接行うハイブリッド検索とベクトル検索

IRISの大きな利点の一つは、SQL内で直接セマンティック（ベクトル）検索を実行でき、従来のフィルターと組み合わせて使えることです。追加のマイクロサービスは不要です。 EMBEDDING() SQL関数は、クエリテキストに対してベクトルをその場で生成し、VECTOR_DOT_PRODUCT のような演算を使って保存済みのベクトルと比較することができます。

例A — 製品のハイブリッド検索（価格フィルターとセマンティックランキング）：

SELECT TOP 3
    p.ProductID,
    p.Name,
    p.Category,
    p.Price,
    VECTOR_DOT_PRODUCT(p.Embedding, EMBEDDING('headphones with ANC', 'my-openai-config')) score
FROM Agent_Data.Products p
WHERE p.Price < 200
ORDER BY score DESC

例B — セマンティックなドキュメントチャンク検索（RAGの回答生成に最適）：

SELECT TOP 3
    c.ChunkID  AS chunk_id,
    c.DocID      AS doc_id,
    c.Title         AS title,
    SUBSTRING(c.ChunkText, 1, 400) AS snippet,
    VECTOR_DOT_PRODUCT(c.Embedding, EMBEDDING('warranty coverage', 'my-openai-config')) AS score
FROM Agent_Data.DocChunks c
ORDER BY score DESC

これがパワフルな理由：価格やカテゴリ、言語、テナント、日付などでの事前フィルタリングと、セマンティック類似度によるランキングを、1つのSQLクエリで実現できます。

---

5) 🔌 Interoperabilityを使って、ライブ（モック）配送APIと連携する

プロジェクトは、IRIS Interoperability*を通じて小さい/api/shipping/status**エンドポイントを公開しています。これにより、「実際の環境」での呼び出しをシミュレートするのに最適です。

curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"orderStatus":"Processing","trackingNumber":"DHL7788"}' \
  http://localhost:52773/api/shipping/status

ポータルでVisual Traceを開き、メッセージの流れをホップごとに確認しましょう（統合のための空港レーダーのようです ✈️）。

---

6) 🤖 エージェントの紹介（smolagentsとツール）

これらのファイルをちょっと見てみましょう。

• agent/customer_support_agent.py — CodeAgentを起動し、ツールを登録します
• agent/tools/sql_tool.py — パラメータ化されたSQLヘルパー
• agent/tools/rag_tool.py — ベクトル検索とドキュメント取得
• agent/tools/shipping_tool.py — Interoperabilityエンドポイントを呼び出します

CodeAgentは、短いコードステップでプランを作成し、あなたのツールを呼び出します。 あなたがツールを用意し、LLMモデルが頭脳を提供します。

---

7) ▶️ 実行しましょう！

ワンショット（簡単なテスト）

python -m cli.run --email alice@example.com --message "Where is my order #1001?"
python -m cli.run --email alice@example.com --message "Show electronics that are good for travel"
python -m cli.run --email alice@example.com --message "Was my headphones order delivered, and what’s the return window?"

インタラクティブなCLI

python -m cli.run --email alice@example.com

Web UI（Gradio）

python -m ui.gradio
# open http://localhost:7860

---

🛠️ 内部の仕組み

エージェントの流れ（シンプルにまとめたもの）

1. 🧭 問題を解決する方法と、使用すべきツールを計画する：例えば、「注文ステータスを確認する → 返品ポリシーを取得する」。

2. 🛤️ 必要に応じて、ツールを呼び出す

• 🗃️ 顧客/注文/製品用のSQL
• 📚 FAQやドキュメント向けの埋め込み表現によるRAG（上記で示したように、EMBEDDING()とベクトル演算を使って、SQL内でRAGをプロトタイプできます）
• 🔌 配送ステータスのためのInteroperability API

3. 🧩 まとめる: 結果をつなぎ合わせて、わかりやすくて正確な答えにする。

ユースケースの拡大に応じて、プロモーション、保証、在庫管理などのツールを追加または差し替えます。

---

🎁 まとめ

これで次を含むコンパクトなAIカスタマーサポートエージェントができました。

• 🧠 LLMの推論（smolagents CodeAgent）
• 🗃️ 構造化データ（IRIS SQL）
• 📚 非構造化知識（IRISベクトル検索 + RAG）— EMBEDDING() を使用してSQLから直接ハイブリッド検索とベクトル検索を実行できるボーナス付き
• 🔌 ライブシステム呼び出し（IRIS InteroperabilityとVisual Trace）