import logging
import os
import re
import warnings
# The Olostep SDK reads this at import time, so set it first
os.environ.setdefault("OLOSTEP_API_TIMEOUT","40")from olostep import Olostep
from qwen_agent.agents import Assistant
from qwen_agent.llm.schema import Message
from qwen_agent.tools.base import BaseTool
from qwen_agent.utils.utils import extract_text_from_message
warnings.filterwarnings("ignore")
logging.getLogger("qwen_agent_logger").setLevel(logging.ERROR)
MODEL = os.getenv("QWEN_MODEL","qwen4-max")
LLM ={"model": MODEL,"model_type":"qwenvl_oai","model_server": os.environ["QWEN_BASE_URL"],"api_key": os.environ["QWEN_API_KEY"],"generate_cfg":{"max_tokens":3000,"extra_body":{"reasoning_effort":"low"},},}
olostep = Olostep(api_key=os.environ["OLOSTEP_API_KEY"])提供:
classRiskGate(BaseTool):
name ="risk_gate"
description =("Scan a notice for payment tactics, threats, urgency, ""secrecy, and suspicious agency links. ""Call once before any other tool.")
parameters ={"type":"object","properties":{"text":{"type":"string","description":("The full notice text, including links ""and payment instructions."),}},"required":["text"],}defcall(self, params,**kwargs):
text = self._verify_json_format_args(params)["text"]
low = text.lower()
flags =[f"scam indicator: {label}"for label, pattern in RULES
if re.search(pattern, low)]
agency =next((
domain
for word, domain in OFFICIAL.items()if re.search(rf"\b{re.escape(word)}\b", low)),None,)if agency:
hosts ={
host_of(url)for url in URL_RX.findall(text)}
flags +=[f"lookalike domain: {host} is not {agency}"for host insorted(hosts)if host andnot is_official_domain(host, agency)]return"\n".join(flags)or"no flags"提供:
classLookupLaw(BaseTool):
name ="lookup_law"
description =("Search for official US legal guidance using ""government websites and Cornell LII. ""Return the most relevant page excerpts.")
parameters ={"type":"object","properties":{"query":{"type":"string","description":"One plain-English legal question.",},"domain":{"type":"string","description":"Optional domain, such as irs.gov.",},},"required":["query"],}def__init__(self):super().__init__()
self.sources =[]defcall(self, params,**kwargs):
args = self._verify_json_format_args(params)
found = olostep.searches.create(
args["query"][:200],
limit=5,
include_domains=([args["domain"]]if args.get("domain")elseNone),
scrape_options={"formats":["markdown"],"timeout":20,},)
pages =[]for link in found.links:
host = host_of(link["url"])ifnot is_allowed_host(host):continue
body =(
link.get("markdown_content")or link.get("description")or"")[:PAGE_CHARS]if body:
self.sources.append(link["url"])
pages.append(f"### {link['url']}\n{body}")iflen(pages)== MAX_PAGES:breakreturn"\n\n".join(pages)or("No official page found. Results outside "".gov and Cornell LII are treated as unreliable. ""Try a shorter query with the statute or agency name.")提供:
SYSTEM ="""You explain a US legal or government notice
to the person who received it, in plain English.
You are not a lawyer.
How to work:
- Read the notice, text or images. Report only what
the document actually says.
- Call risk_gate once with the notice text before
using any other tool.
- Treat risk_gate flags as evidence, not proof.
Flags can make a notice suspicious but cannot
establish that it is legitimate.
- If the notice is plainly fraudulent, say so and
skip research.
- Otherwise, call lookup_law with one plain question
about the main legal issue.
- Call lookup_law a second time only if the first
call returns no official page.
- Never invent a law, citation, phone number, amount,
or deadline.
- Report deadlines using the document's own words.
Separate a stated deadline from whether it is credible.
- If a returned page does not verify a claim,
explicitly say it could not be verified.
- Never suggest ignoring a legal notice.
- Separate what the document establishes from
what is assumed.
- Keep each section under 80 words.
- Use plain English, short sentences, and bullets.
- Avoid em dashes and contractions.
Begin with this verdict block:
**Scam:** yes, probably, or no
(confidence: low, medium, or high).
**Time sensitive:** yes or no, followed by the
exact deadline in the document, or "no deadline stated".
**Demand:** the amount and what the document asks
for, or "nothing is demanded".
Then write these sections in order:
### Summary
Explain what the document is and what happens
if nothing is done. Use 3 or 4 sentences.
### Evidence
Include one bullet per important finding.
Quote the document or the official page where
possible. Include risk_gate flags.
If the scan returned no flags, explicitly say so.
No flags is not proof that a notice is legitimate.
### Next steps
Give numbered actions in the order they should
be taken.
If the notice threatens eviction, foreclosure,
a lawsuit, arrest, or deportation, the first action
must be to contact a qualified attorney or legal aid.
Explain that waiting creates a risk.
Never confuse a document's claimed deadline with
a verified legal deadline.
Do not include a sources section or legal disclaimer.
The application appends both."""提供:
NO_SOURCE =("No official page was retrieved for this notice, ""so treat any legal statement above as unverified.")
DISCLAIMER =("\n---\n""**Not legal advice.** Verify deadlines and citations ""with the issuing authority, using contact details ""you find independently, not those printed in the notice.")提供:
from IPython.display import Markdown
FICTIONAL_NOTICE ="""
INTERNAL REVENUE SERVICE
NOTICE OF FINAL DEMAND
Date of Notice: November 10, 2026
Our records show an outstanding balance of
$4,870.00 in federal income tax for tax year 2024.
You must resolve this balance within 24 hours.
Failure to comply will result in a warrant for your
arrest and your wages being garnished.
Do not discuss this notice with anyone.
Pay using Apple or Google Play gift cards and
provide the card numbers over the phone, or by
wire transfer through:
https://irs-gov-payments.top/pay?ref=MW4471
""".strip()
Markdown(analyze_notice(text=FICTIONAL_NOTICE))提供:
政府からの通知を受け取って、それが本物なのか、対応が必要なのか、あるいは詐欺ではないかと迷ったことはありませんか?
法的通知は読みづらく、複雑な言い回しに支払い要求や期限が混ざると一層わかりにくくなります。詐欺師はこの混乱につけ込み、政府機関になりすまして不必要な緊迫感を煽ります。
本チュートリアルでは、Qwen4-MaxとQwen-Agentフレームワークを使って、米国の法的通知アナライザーを構築します。アプリケーションはテキスト・画像・PDFを受け付け、疑わしい支払い手口にフラグを立て、必要に応じて公式の法情報リソースを検索して検証します。
大規模言語モデル(LLM)だけに全面的に依存するのではなく、Pythonの2つのツールを組み合わせます。1つ目は正規表現で一般的な詐欺の兆候を捉えます。2つ目はOlostepを使って、米政府の公式サイトやCornell Legal Information Institute(LII)を検索します。
要点まとめ
Qwen4-Maxとは?
Qwen4-Maxは、2026年11月16日に公開されたQwen4ファミリーのAlibabaによるフラッグシップモデルです。スパースMixture-of-Experts(MoE)構成に改良を加え、ネイティブなビジョン機能と大きなコンテキストウィンドウを備え、複雑な推論やエージェント的アプリケーション向けに設計されています。
本プロジェクトに特に関係する機能は次のとおりです。
以下はAlibabaの発表に掲載されたベンチマーク結果で、Qwen4-MaxがQwen3.8-Maxに対し、Alibabaが評価したほぼ全能力で改善していることが示されています。
図1:Qwen4-Maxのベンチマーク結果。画像出典:Qwen, Qwen4-Max: Your New Teammate Has Arrived。
法的通知アナライザーはどう動く?
このアナライザーは単一のQwen-Agentアシスタントで構成され、2つのPythonツールを連携させます。文書理解と推論はQwen4-Maxが担います。コードを書く前に、ワークフローを確認しましょう。
図2:法的通知アナライザーのワークフロー。
ワークフローは6ステップです。
risk_gateを呼び出し、疑わしい支払い指示、脅し、リンクを確認する。lookup_lawを呼び出し、公式の法情報を検索する。重要な設計判断は、LLMがすべてを行わないことです。決定的なチェックはPythonが担当し、外部調査はOlostepが担当し、文書理解と推論はQwen4-Maxが担当します。
これによりワークフローはシンプルに保たれ、各作業に適したツールが使えます。エージェントの用語が初めてであれば、Introduction to AI Agentsコースで、コード不要の基本を学べます。
1. 環境のセットアップ
Jupyter Notebook、モデルアクセスにQwenCloud、ウェブ検索とスクレイピングにOlostepを使用します。
まず、QwenCloudでアカウントを作成し、クレジットを追加またはトークンプランに加入し、ダッシュボードからAPIキーを発行してください。QwenCloudは選択したリージョンに基づくAPIエンドポイントを提供します。
法的リサーチ用にOlostepのAPIキーも必要です。
Jupyter Notebookを起動する前に、ターミナルで環境変数を設定してください。
os.environを使ってノートブック内で設定することもできます。ここでは割引価格でモデルにアクセスできるトークンプランのエンドポイントを使用しています。従量課金の場合は、QwenCloudがリージョンに応じて表示するエンドポイントを使用してください。
次に、ノートブックで必要な依存関係をインストールします。
ragエクストラは、PDF読み取りに使うpdfplumberなどの文書処理パッケージを追加します。バージョン0.0.34時点では、Qwen-Agentはsoundfileとtqdmを依存関係に明記せずに起動時に読み込むため、両方を明示的にインストールします。Qwen4-Maxの設定
次に、モデルとOlostepクライアントを初期化します。ここではシンガポールリージョン(トークンプラン有)を使用します。
これで、Qwen4-Maxはマルチモーダル入力に対応し、推論負荷を設定し、リサーチクライアントを初期化します。
OLOSTEP_API_TIMEOUTはSDKが読み込み時に参照するため、インポート前に設定します。押さえておきたい設定項目は次のとおりです。
modelは使用するモデルを指定します。model_typeはOpenAI互換のマルチモーダルIF経由で画像を送るための指定です。model_serverはQWEN_BASE_URLのエンドポイントを指します。max_tokensは生成レスポンスの長さを制限します。reasoning_effortはモデルの推論量を制御します。ここでは応答を速くするためlowを使用します。OLOSTEP_API_TIMEOUTはリサーチ要求のタイムアウト(秒)を設定します。再利用可能なエージェントヘルパーの作成
テキストと画像の両方を処理するため、エージェントを実行する再利用可能な関数を作りましょう。
この関数は、プロンプトと任意の画像をQwen-Agentに送り、最終応答を待って、生成テキストを取り出します。
PDFを読むためのヘルパーも必要です。
この関数は、PDFの各ページから選択可能なテキストを抽出し、1つの文字列に結合します。
注意:pdfplumberはOCRを行いません。画像のみのスキャンPDFは、各ページを画像としてレンダリングし、直接Qwen4-Maxに送ってください。
2. リスクゲートによる詐欺検出の構築
最初のカスタムツールは、疑わしい挙動を特定します。LLMにすべての怪しい支払い指示の認識を任せるのではなく、既知の詐欺手口は正規表現で検出できます。
これは高速で決定的、しかもトークンを消費しません。構文の復習が必要なら、Regular Expressions in Pythonコースを参照してください。
詐欺検出ルールの定義
まず、正規表現のリストと、政府機関とその公式ドメインの対応表を用意します。
このコードは詐欺の指標を定義し、機関名をその機関が実際に使用するドメインにマッピングします。例えば通知にIRSが言及されていれば、アプリはそのリンクをirs.govに照らして確認します。
ドメインの抽出と検証
次に、URLからホスト名を取り出すヘルパーが必要です。
これはホスト名を抽出し、それが公式ドメインまたは正当なサブドメインかを確認します。区別は重要です。単純な
endswith()チェックでは、fakeirs.govをIRSのサイトと誤認してしまいます。リスクゲートツールの実装
これで、これらのルールをカスタムQwen-Agentツールにまとめられます。
このツールは、通知の文章に一致するパターンを走査し、URLを機関の公式ドメインと照合し、疑わしい指標を返します。機関名は単語全体としてマッチさせるため、"irs"が"first"のような単語で誤検出されることはありません。
例えば、テスト1の架空のIRS通知では次の結果になります。
エージェントはこれらの結果をコンテキストとして受け取り、通知が疑わしいかどうかを判断する際に利用します。
3. 法的リサーチツールの作成
2つ目のツールは外部リサーチを扱います。エージェントに無作為なサイトや掲示板、法律事務所のブログを検索させ、それを権威ある情報として扱わせたくはありません。
代わりに、米国政府の公式サイトとCornell LIIにリサーチを限定します。Olostepは1回のリクエストで複数の結果を検索・スクレイピングできるため採用します。他の選択肢と比較したい場合は、Firecrawlのチュートリアルをご覧ください。
リサーチ制限の定義
まず、許可する情報源と取得量の上限を定義します。
is_allowed_host()は.govサイトとCornell LIIを許可します。is_official_domain()を再利用するため、fakelaw.cornell.eduのようななりすましは拒否されます。保持するページは最大2件、1ページあたり最大3,000文字に制限します。LookupLawツールの実装
では、2つ目のカスタムツールを作成します。
このツールはOlostepに検索リクエストを送り、結果をフィルタし、ページ内容を抽出し、選択した抜粋をQwen4-Maxに返します。
実装上の注意点は3つあります。
self.sourcesに保持し、分析後にアプリケーションが表示できるようにします。4. Qwen-AgentとQwen4-Maxでエージェントを構築
カスタムツールはそろいました。
risk_gateは疑わしい挙動を特定し、lookup_lawは関連する法情報を取得します。次に、これらを調整するエージェントを作成します。単一のシステムプロンプトで、ワークフロー、ツールの順序、応答形式を定義します。こうした構成にはQwen-Agent以外の選択肢もあり、別フレームワークはDeveloping LLM Applications with LangChainコースで扱っています。
システムプロンプトの定義
このプロンプトは、エージェントの責任範囲を定め、法情報をでっち上げないよう指示します。特に注意すべき指示は「期限」です。
不正な通知であっても期限が記載されている場合があるため、エージェントは文書の主張として期限を報告しつつ、その信頼性を説明しなければなりません。
免責文と言及元の処理を追加
免責文はシステムプロンプト外に置き、Python側で一貫して付与します。
これにより、法的リサーチで公式ソースが得られなかった場合のメッセージを用意でき、すべての応答に免責文が付与されます。
メインの分析関数を作成
最後に、すべてを1つの再利用可能な関数で接続します。
この関数は、各文書に新しいエージェントを作成し、分析を実行し、取得した情報源を収集し、最終応答を返します。各通知が独自のソースリストを持てるように、
LookupLaw()は関数内で生成します。5. 法的通知アナライザーのテスト
これで法的通知アナライザーが動作します。次の3つのサンプル文書でテストします。
各テストはワークフローの異なる部分を検証します。
テスト1:IRSの詐欺レター
最初の例は架空のIRS詐欺レターです。受取人が2024年課税年度の連邦所得税$4,870を負っており、24時間以内に支払う必要があると主張します。
逮捕の脅し、ギフトカードや電信送金での支払い要求、疑わしいウェブサイトも含まれます。サンプル入力は次のとおりです。
これは架空の通知を作成し、分析のためにエージェントへ送信します。
出力:
図3:架空のIRS詐欺レターに対するアナライザーの出力。
スキャナーはいくつもの疑わしい指標を検出し、エージェントは外部の法的リサーチをスキップしました。明らかな詐欺ではこれが望ましい動作です。決定的チェックがすでに不正を示している場合、アプリは追加のリサーチでトークンを浪費しません。
このテストが示すこと: リスクゲートは一般的な詐欺手口を特定し、不要な外部リサーチを避ける判断をエージェントに助けます。
テスト2:立ち退き通知の写真
2つ目のテストはQwen4-Maxのネイティブビジョンに焦点を当てます。自分でテキスト抽出せず、立ち退き通知の写真をそのままモデルに送ります。
サンプルはフロリダの3日通知で、$1,850の未払い家賃、または2026年11月23日までの物件明け渡しを求めています。コードは次のとおりです。
写真をそのままQwen4-Maxに送るため、別のOCRパイプラインは不要です。Qwenのビジョンとツール呼び出しを組み合わせた別の構築例は、請求書処理を扱うQwen 3.6 Plus APIチュートリアルを参照してください。
出力:
図4:立ち退き通知の写真に対するアナライザーの出力。
モデルは写真を理解し、金額と期限を抽出し、通知の種類を特定しました。取得した法情報ページが条文を検証するのに十分ではなかったことを認め、サンプル文書の署名欄や送達欄の空欄も指摘しました。
このテストが示すこと: Qwen4-Maxは撮影された法的文書を直接解釈でき、Qwen-Agentは追加のリサーチを調整し、不確実性を伝えられます。
テスト3:差止め要求のPDF
最後のテストでは、2ページの差止め要求レター(PDF)を使用します。
文書は17 U.S.C. § 501および512を引用し、著作権侵害を主張し、2026年11月28日までに問題のコンテンツの削除と遵守確認を求めます。PDFには選択可能なテキストが含まれるため、
read_pdf()ヘルパーが使えます。コードは次のとおりです。これはPDF内容を抽出し、そのテキストを同じエージェントに送ります。
出力:
図5:差止め要求レターに対するアナライザーの出力。
エージェントは、私的な法的要求と政府・裁判所の公式通知を正しく区別しました。金銭の要求がないことを認識し、推奨事項を調整しています。リサーチツールは、米国著作権局の関連ページを取得し、最終的な出典として表示されました。
このテストが示すこと: 同じエージェントがPDFの往復書簡も扱え、法的要求の性質を見極め、適切な次のアクションを提案できます。
Qwen4-Maxの所感:良い点・悪い点・気になる点
本プロジェクト、他のエージェント的アプリ、そしてvibe codingでQwen4-Maxを使ってみての率直な評価です。
良い点
Qwenのエコシステムは多機能です。音声認識、音声合成、ウェブ検索、スクレイピング、そしてゼロから実装せずにエージェント的アプリを作れるオープンソースのツールキットを含みます。
最も良かったのは、Qwen4-Maxが詳細な指示にしっかり従ったことです。要求した出力構造を概ね守り、文書から日付を抽出し、テスト中は正確な要約を生成しました。
画像理解は突出していました。法的通知の写真を与えると、追加のOCRパイプラインなしで内容を読み取り、文書中心のエージェント的アプリには大きな助けになります。
悪い点
最大の問題は速度でした。Qwen4-Maxはvibe coding向けの第一候補ではありませんでした。DeepSeek V4.1 Flashや他モデルと比べ、単純な作業でも完了までに明らかに時間がかかることが多かったです。
生成速度は毎秒約100トークンを見ることがありましたが、その数値は実コストを隠します。モデルは単純な変更にも長く推論し、簡単な修正を頼んでも、想定以上に待たされることがありました。
より高速な選択肢を試したい場合は、DeepSeek V4.1 Flash APIチュートリアルで取り上げています。
気になる点
ネイティブのウェブ検索が最も厄介でした。テストでは応答時間が不安定で、同じクエリが数秒で返ることもあれば1分近くかかることもあり、なかには400秒超で完了しないリクエストもありました。
リサーチワークフローを3回走らせるのに約16分かかったこともあります。外部の法情報に依存するアプリとしては信頼性に欠けました。
そのため、ネイティブ検索をOlostepに置き換える必要があり、当初の計画どおりQwenエコシステムだけに頼ることができなくなりました。
また、DeepSeek Harnessを試した際にも問題に遭遇しました。株式市場の調査に関する単純な質問をしただけなのに、ワークフローが長時間リクエストに費やした末にエラーを返しました。単純なタスクとしては不満の残る結果でした。
総じて、Qwen4-Maxは印象的な能力を備えていますが、推論のオーバーヘッドとネイティブ検索の不安定さは、本番ワークフローに採用する前に考慮すべき点です。Qwenモデルでの構築を続けたい場合は、Qwen 3.7 Max APIチュートリアルで自己レビュー型の生産性エージェントを解説しています。