記事の説明:AI Chat v2 は、従来の会話インターフェースのシンプルな呼び出し方を維持しながら、マルチモーダル入力、構造化イベントストリーム、自動ツール呼び出し、一時停止と再開、非同期実行、セッション管理を追加しています。本稿では、ほとんどコードを書き換えずに済む移行から始め、これらの変化が実際のプロダクト開発にどのような影響を与えるかを解説します。
多くのチャットインターフェースは、デモ段階では非常に使いやすいものです。質問を渡し、モデルが一段落のテキストを返すのを待ち、そのテキストをページに表示するだけです。
プロダクトがさらに先へ進むと、もはや「一つ聞いて、一つ答える」だけではなくなります。ユーザーは PDF やスクリーンショットをアップロードし、モデルはウェブを検索し、ファイルを読み取り、さらには承認済みの GitHub、Notion などのツールを呼び出す必要があります。一つのタスクは複数ラウンドにわたる可能性があり、途中で情報不足のために止まり、追加質問をすることもあります。この時、インターフェースが依然として増え続けるテキスト文字列しか返さない場合、フロントエンドはモデルが何をしているのかを把握しにくく、バックエンドもタスクが本当に終了したかどうかを判断しにくくなります。
Ace Data Cloud AI Chat v2 API が解決するのは、まさにこの問題です。従来の会話方式を覆すのではなく、シンプルな呼び出しとの互換性を保ったまま、一つの回答をプログラムが識別・処理できるイベントに分解します。本文は本文、ツール呼び出しはツール呼び出しとして扱われ、引用、ファイル、エラー、最終状態にはそれぞれ明確な場所があります。

図:AI Chat v2 はタスク全体を一段落のテキストに押し込めるのではなく、入力、ツール、出力イベントの構造を維持します。
¶ 移行は、まず一つのアドレスを変更することから始められます
プロジェクトで旧版の /aichat/conversations を使用している場合、先にメッセージ構造を書き換える必要も、先に Agent インターフェース一式を作る必要もありません。V2 は引き続き、従来の model、question、stateful、id、references、preset などのフィールドを受け付けます。最小限の移行は、リクエスト先アドレスを次のように変更するだけです。
https://api.acedata.cloud/aichat2/conversations
最も基本的なリクエストも、依然として短いままです。
curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR_API_TOKEN' \
-H 'content-type: application/json' \
-d '{
"model": "YOUR_SUPPORTED_MODEL",
"question": "请概括这份需求里最重要的三个问题。",
"stateful": true
}'
通常の JSON モードでは、インターフェースは引き続き見慣れた結果を返します。
{
"answer": "...",
"id": "conversation-uuid"
}
返された id を保存し、次回のリクエストで同じ id を渡せば、会話を継続できます。stateful のデフォルト値は true であり、保存済みセッションのコンテキストを読み込み、継続するかどうかを制御するために使用されます。
このステップは実際のプロジェクトに非常に適しています。まず認証、モデル、レイテンシ、既存業務が正常かどうかを検証し、その後で新しい機能を段階的に統合できます。移行を、UI の再構築と同じリリースに結び付ける必要はありません。
¶ ファイルと画像が会話に加わると、順序も情報になります
旧版の question は純粋なテキストに適しています。「まずレポートを確認し、次にスクリーンショットと照合し、最後に結論を出す」といったタスクになると、単純な添付ファイル一覧では十分に正確ではありません。V2 では構造化された message 配列が追加され、テキスト、画像、ファイルを順序どおりに配置できます。
{
"model": "YOUR_SUPPORTED_MODEL",
"stateful": true,
"message": [
{
"type": "text",
"text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
},
{
"type": "file_url",
"file_url": {"url": "https://example.com/report.pdf"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/dashboard.png"}
}
]
}
利用可能なコンテンツブロックには、text、image_url、file_url があります。重要なのは単に「添付ファイルをサポートする」ことではなく、コンテンツ間の関係が転送時に失われないことです。クライアントは、どの段落がタスクの説明であり、どのファイルが元資料であり、その次に何を比較すべきかを、モデルに明確に伝えられます。
旧クライアントをスムーズに移行させるため、V2 は引き続き references を認識します。画像拡張子に対応する URL は画像として処理され、その他の URL はファイルとして処理されます。単にインターフェースをアップグレードするだけであれば、従来の書き方を一時的に維持できます。入力順序が理解に影響する場合は、message の使用を推奨します。
¶ ストリーミング応答は、もはや「入力中」だけではありません
従来のストリーミング出力には、通常テキストの増分しかありません。モデルが検索を開始したり、ファイルを読み取ったり、外部ツールを呼び出したりすると、ページは停止しているように見え、ユーザーはタスクが継続しているか分からず、開発者も明確な状態を取得できません。
AI Chat v2 は、accept リクエストヘッダーを通じて、3 種類の応答方式を提供します。
| 使用シーン | accept |
返却方式 |
|---|---|---|
| シンプルなサーバーサイドリクエスト | application/json |
完了後に {answer, id} を返す |
| Node、Python、CLI または Worker | application/x-ndjson |
1 行につき 1 つの JSON イベント |
| Web フロントエンド | text/event-stream |
SSE イベントストリーム |
NDJSON および SSE モードでは、返されるのは token だけではなく、型を持つイベント群です。text_delta は本文の増分に使用され、tool_use はモデルがツールを呼び出す準備をしていることを示し、tool_result はツール結果を返し、citation は引用元を提供します。card と artifact は個別に表示可能なカードまたは成果物を保持し、error はこのラウンドの失敗を示し、done は使用量と終了理由を示します。
以下の Python コンシューマーは、本文を連結しながら重要な状態を保持します。
import json
import os
import requests
url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
"accept": "application/x-ndjson",
"authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
"content-type": "application/json",
}
payload = {
"model": os.environ["ACEDATA_CHAT_MODEL"],
"question": "检索资料,给出带来源的简要结论。",
"stateful": True,
}
with requests.post(url, json=payload, headers=headers,
stream=True, timeout=120) as response:
response.raise_for_status()
answer = []
for raw_line in response.iter_lines():
if not raw_line:
continue
event = json.loads(raw_line)
event_type = event.get("type")
if event_type == "text_delta":
answer.append(event.get("content", ""))
elif event_type == "tool_use":
print("开始调用:", event.get("tool_name"))
elif event_type == "tool_result":
print("工具是否失败:", event.get("is_error"))
elif event_type == "error":
raise RuntimeError(event.get("message", "未知错误"))
elif event_type == "done":
print("用量:", event.get("usage"))
print("终止原因:", event.get("terminal_reason"))
print("".join(answer))
製品が最終テキストだけを重視する場合は、すべての text_delta.content を連結すればよいです。観測可能な Agent インターフェースを作成する場合は、ツール呼び出し、引用、成果物、状態をそれぞれレンダリングできます。どちらの要件でも同じインターフェースを使用でき、「シンプルなチャット」と「複雑なタスク」のために2セットのプロトコルを維持する必要はありません。
¶ ツール呼び出しはデフォルトで利用可能ですが、製品側では依然として境界を明確にする必要があります
V2 では、モデルがタスクの必要に応じて Web 検索、ページ抽出、ファイル読み取りなどの組み込み機能を呼び出せます。ユーザーが該当するサービスを接続して認可した後は、MCP ツールを使用して GitHub、Notion などの外部データも処理できます。
ストリームには tool_use と tool_result がそれぞれ出現し、両者は tool_id によって対応付けられます。フロントエンドではこれに基づいて実際の進捗を表示でき、バックエンドでは各ツールの所要時間と失敗箇所を記録できます。
ツールを自動で呼び出せることは、実行範囲を無制限に開放すべきことを意味しません。max_turns は1回のリクエストにおける Agent の反復回数を制約するために使用され、ドキュメントで示されている範囲は1〜500です。1 に設定した場合、このターンではモデル呼び出しを1回だけ行い、ツール呼び出しには進みません。本番環境では、タスクの複雑さ、応答時間、コスト予算に応じて積極的に設定すべきであり、長期的に大きなデフォルト上限に依存すべきではありません。
Webhook、CI/CD、または監視タスクの場合、V2 は async: true をサポートしており、タスクをバックグラウンドで実行し、照会または callback_url を通じて結果を取得できます。ただし、送信、公開、書き込みに関わる操作については、allowed_skills、allowed_mcp_servers、または unattended_policy を通じて明示的に事前認可する必要があります。
接続が解決するのは「アクセスできるか」であり、認可ポリシーが解決するのは「今回ユーザーに代わって行動してよいか」です。この2つを混同してはいけません。
¶ Agent に情報が不足している場合、タスクが完了したふりをする必要はありません
複雑なタスクは、具体的な問題で行き詰まることがよくあります。どのチャンネルに公開するか、どの形式を採用するか、既存のファイルを上書きするか。V2 はこのために ask_user_question イベントを提供しています。イベントが出現すると、会話はユーザー入力を待つ状態に入ります。
クライアントは現在の会話の id と対応する tool_id を保存し、質問を表示して回答を収集した後、同じ会話の id を使用して tool_results 経由で回答を返すと、タスクは一時停止地点から続行できます。この仕組みは承認ノードの作成にも適しています。情報が不足しているときにモデルに推測させるよりも、不足している選択をユーザーに返すほうがよいです。
¶ 会話自体も管理できます
V2 は同じエンドポイントに軽量な会話 CRUD を追加しており、action によって retrieve、retrieve_batch、update、delete を区別します。
retrieve_batch は完全な messages を含まずに要約を返すため、会話サイドバーに適しています。ユーザーが実際に会話を開くときに、retrieve を呼び出して本文を読み取ります。長い会話では、サーバー側のコンテキスト整理によっても、保存済みの元のメッセージが要約で上書きされることはありません。記事を引き続き修正する、数値を確認する、または公開準備をする必要がある場合は、要約で本文を代用せず、原文を読み取るべきです。
¶ リリース前に、「テキストが返ってくるか」だけを検証しないでください
Agent インターフェースを統合した後、部分的なテキストを受信したことは、このターンが確実に完了したことを意味しません。ストリームの終了も、タスクの成功を必ずしも意味しません。クライアントは error を処理し、done を受信した後に usage と terminal_reason を記録すべきです。SSE では、[DONE] は転送の終了のみを示し、それ以前に発生したエラーイベントを覆い隠すことはできません。
API Token はサーバー側にのみ保存すべきです。ストリームパーサーはネットワークの分割や一時的に認識できない新しいイベントを処理できる必要があります。ツール呼び出しは tool_id によって対応付けるべきです。引用リンクと成果物は安全にレンダリングする必要があります。書き込み可能な接続では、引き続き人間による確認、または十分に限定された無人実行認可を保持してください。モデル名、料金、利用可能な機能は更新される可能性があるため、正式に統合する際は現在のドキュメント、サービスページ、コンソールを基準にし、サンプル設定を長期間固定で書き込まないでください。
AI Chat v2 で最も注目すべき点は、チャットウィンドウにいくつかのボタンを追加することではありません。それは、アプリケーションがついに1回の AI タスクの内部で何が起きているかを確認できるようにすることです。モデルがいつテキストを出力し、いつツールを呼び出し、どこでユーザーを待ち、どのような状態で終了するのかです。
既存のプロジェクトがまだ通常の質問回答ボックスにすぎない場合は、まずインターフェースのアドレスを変更し、元のリクエストボディをそのまま使用できます。この段階が安定してから、message、NDJSON または SSE、ツールタイムライン、一時停止と再開を統合してください。アップグレードは小さくても、その後の製品形態のために十分に大きな余地を残します。
