はじめに
Notion が Agent API をパブリックベータとして正式公開しました。これまでプライベートアルファ版として限定提供されていた Custom Agent 連携機能が、誰でも利用できる形で開放されたことになります。
セッションベースのチャット開始、返信のストリーミング受信、アクション送信、イベント履歴のページングに加え、Custom Agent 自体をプログラマティックに検索・管理する API も同時に追加されました。Slack ボットや社内ツール、モバイルクライアントなどに Custom Agent を組み込みやすくなる、実用性の高いアップデートです。
一方で、プライベートアルファ版のルート（agents / threads / messages / chat）は 2026年9月30日 に廃止予定 となっており、これらを既に利用しているプロジェクトは期限内の移行が必須です。本記事ではこの変更点と対応方法を整理します。
📌 影響を受ける人
- Notion Agent API のプライベートアルファ版（agents/threads/messages/chat）を利用中の開発者
- これから Custom Agent を外部ツール（Slack、社内システムなど）に組み込みたい開発者
- Notion 上で Custom Agent の運用・利用状況を管理したい開発者・管理者
変更の全体像
パブリックベータでは、チャット機能を担う「Sessions API」と、エージェント自体を管理する「Agent 管理 API」の2系統が用意されています。アルファ版からの主な変化は、threads/messages という概念が sessions/events に置き換わった点です。
チャットのやり取りの流れは、以下のようなセッションベースのフローになります。
変更内容
今回のアップデートは大きく3つに分類できます。
| # | 変更 | severity | 概要 |
|---|---|---|---|
| 1 | Agent API パブリックベータ公開 | 🔴 high | セッション作成・ストリーミング・アクション送信・イベント履歴ページングが可能に |
| 2 | Custom Agent 管理 API 追加 | 🟡 medium | エージェント検索、利用状況取得、クレジット上限設定、有効/無効化・削除（個別/バッチ） |
| 3 | アルファ版ルートの廃止（Breaking Change） | 🔴 critical | agents/threads/messages/chat が2026-09-30に終了。sessions/events ベースの新APIへ移行必須 |
その他、既存 changelog 内の表記が「custom agents」→「Custom Agents」に統一されていますが、これは機能面には影響しないドキュメント修正です。
1. Sessions API（チャット機能)
- Custom Agent とのチャットセッションを開始できる
- 返信をストリーミングで受信できる
- セッション内でアクション（ツール呼び出しに近い操作）を送信できる
- セッションのイベント履歴をページングで取得できる
クイックスタートではパーソナルアクセストークンを使った最初のリクエストがエンドツーエンドで解説されており、既存の Notion API と同じ認証フローで扱える点も扱いやすいポイントです。
2. Agent 管理 API
| API | できること |
|---|---|
| Query agents | トークンからアクセス可能なエージェントを検索 |
| Retrieve agent insights | エージェントごとの利用状況を取得 |
| Agent management (batch) | クレジット上限設定、有効化/無効化、削除を個別・非同期バッチで実行 |
複数の Custom Agent を組織で運用している場合、コスト管理やガバナンスの観点で活用しやすい API 群です。
3. 破壊的変更：アルファ版ルートの廃止
⚠️ Breaking Change
プライベートアルファ版のagents/threads/messages/chatルートは 2026年9月30日 に廃止されます。継続利用しているシステムは、それまでにパブリックベータ版 API へ移行する必要があります。
主な差分は次の通りです。
影響と対応
-
アルファ版利用者: 「Upgrading to public beta」ガイドに従い、リクエスト形式・レスポンス形式の両方を見直す必要があります。単なるエンドポイント変更ではなく、データモデル（
threads/messages→sessions/events）が変わる点に注意してください。 - これから導入する開発者: 最初からパブリックベータ版 API で実装すれば、今回の移行対応は不要です。
- Custom Agent を複数運用している組織: 新しい管理 API を使うことで、利用状況の可視化やクレジット管理を自動化できます。
💡 Tips
移行期限（2026-09-30）まで約1か月しかないため、アルファ版ルートを使っているコードがある場合は棚卸しを早めに行うのがおすすめです。
コード例
概念を掴みやすいよう、リクエストの構造がどう変わるかを簡略化した疑似コードで示します（実際のフィールド名は公式の移行ガイドを参照してください）。
Before（プライベートアルファ版：クエリパラメータ + threads/messages）
# クエリパラメータでスレッドを指定して会話を継続するイメージ
curl "https://api.notion.com/v1/agents/chat?thread_id=xxxx&agent_id=yyyy" \
-H "Authorization: Bearer $NOTION_TOKEN"
After（パブリックベータ版：JSONボディ + sessions/events）
# セッションを開始
curl -X POST "https://api.notion.com/v1/sessions" \
-H "Authorization: Bearer $NOTION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "yyyy",
"message": "今週のタスク一覧を教えて"
}'
# セッションのイベント履歴をページングで取得
curl -X GET "https://api.notion.com/v1/sessions/{session_id}/events?page_size=50" \
-H "Authorization: Bearer $NOTION_TOKEN"
クエリパラメータでの操作が JSON リクエストボディに置き換わり、「スレッド」という概念が「セッション」と「イベント」という単位に整理されているのがポイントです。
まとめ
- Notion Agent API がパブリックベータとなり、Custom Agent とのチャット・アクション送信・イベント履歴取得がAPI経由で可能に
- Custom Agent の検索・利用状況取得・クレジット管理などのプログラマティック管理 API も同時追加
- プライベートアルファ版（agents/threads/messages/chat）は2026年9月30日に廃止予定。利用中の場合は早急な移行が必要
- 新API は JSON ボディベースで、
threads/messagesはsessions/eventsに置き換わる
Custom Agent を業務フローに組み込みたい開発者にとっては待望のアップデートですが、既存のアルファ版利用者は移行期限を意識したスケジュール調整を忘れずに行いましょう。