月曜朝、Slackの質問スレッドから社内規程を知っているCustom Agentを呼び出そうとして、古いサンプルのthread_idをどこへ渡すのか分からず手が止まる。
Notionの公式ページにはalpha期のAgent SDK表記も残っているため、検索で見つけたコードをそのまま使うと、現在のsessionsと噛み合わないことがあります。
このつまずきを解消する鍵が、2026年8月20日に公開ベータとなったNotion Agent APIsと、新しいSessions／Eventsモデルです。
2026年8月現在、Notion Agent APIの使い方は、既存のCustom Agentを選び、POST /v1/sessionsで会話を開始し、SSEまたはイベント履歴から返答を受け取る流れが基本です。Notionは2026年8月20日にNotion Agent APIsを公開ベータへ移行し、外部アプリからセッション開始、継続メッセージ、承認・拒否アクション、履歴取得まで扱えるようにしました。
- 新規実装：
agents、sessions、eventsを中心に設計し、Custom AgentはNotionアプリで先に作成します。 - リアルタイム表示：
Accept: text/event-streamを付け、永続化するのはevent.committedです。 - 旧alpha版：
threadsとmessagesを使う実装は、2026年9月30日までに移行が必要です。
対象読者：Notion Custom AgentをSlack bot、社内ポータル、モバイルアプリへ組み込みたい開発者・PM・情報システム担当者。
最初に確認すること：コードベースに/threads、/messages、/chatStreamが残っていないか検索してください。
APIパス、制限、料金、SDKの範囲を2026年8月28日の一次情報で照合し、実装と移行に必要な点へ絞って整理します。
8月20日の公開ベータで変わったこと
Notionは公式Changelogの2026年8月20日付エントリで公開ベータ開始を発表しました。中心は、外部アプリとCustom Agentの会話を保持するSessionです。
| 公開ベータで扱える処理 | 外部アプリ側でできること | 主なAPI |
|---|---|---|
| Custom Agentの検索 | トークンから利用可能なAgentを選ぶ | POST /v1/agents/query |
| 会話の開始・継続 | Slackスレッドやアプリ画面からメッセージを送る | POST /v1/sessions |
| 応答のストリーミング | 生成途中からUIへ表示する | POST /v1/sessionsとSSE |
| アクションと履歴 | 承認・拒否を返し、返答や状態遷移をページングする | /v1/sessions配下 |
| 利用状況と管理 | 実行回数・クレジット・状態・上限を扱う | /v1/agents配下 |
会話状態、返答、承認待ち、エラーをSessionとEventで一貫して追える点が重要です。公式OverviewはSlack bot、社内ツール、モバイルクライアントを組み込み先に挙げています。
8月27日にはNotion MCPもSessionsへ対応
2026年8月27日にはNotion MCPにもSessionの検索・開始・継続・停止・イベント取得ツールが追加されました。MCPクライアントならツール群、独自UIならHTTP APIと使い分けます。
似た名前のAPIを混同しない
検索上は「Notion Custom Agent API」とも呼ばれますが、公式名称はNotion Agent APIsです。これは作成済みCustom Agentを外部アプリから呼ぶAPIで、製品ページのExternal Agents APIは外部AgentをNotionへ参加させます。方向を取り違えないでください。
Workersを含む全体像は、既刊のNotion AIエージェント連携とWorkers・API実装ガイドで確認できます。
リクエスト前にそろえる3つの前提
Custom AgentはNotionアプリで先に作る
Sessions APIはCustom Agentを新規作成しません。公式Quickstartも既存Agentを前提とし、一覧から得たidをagent_idへ渡します。
Custom Agentsは2026年8月28日時点でBusiness／Enterprise向けです。検証環境のプランも確認してください。
PATとconnection tokenでは権限の見え方が違う
PATは発行ユーザーとして到達できるAgentへアクセスします。connection tokenはAgent操作のcapabilityを有効にし、接続先として明示したAgentを扱います。
Custom Agentには独自のアクセス権があります。公式権限ガイドによると、利用者が直接閲覧できない情報もAgent経由で届く可能性があります。Tools and Accessと利用者範囲を一緒に監査してください。
共通ヘッダーは固定して管理する
公開ベータの各リファレンスで確認できるAPIバージョンは2026-03-11です。すべてのリクエストでAuthorizationとNotion-Versionを付け、POSTではContent-Typeも指定します。トークンはブラウザやモバイルアプリへ埋め込まず、自社バックエンドのシークレットとして保持してください。
Authorization: Bearer <token>Notion-Version: 2026-03-11Content-Type: application/json- SSEを使うときだけ
Accept: text/event-stream
threadsとmessagesはsessionsとeventsへ変わった
private alpha版からは、名前だけでなくHTTPメソッド、入力、ストリーム、statusも変わります。公式の移行ガイドの対応関係は次のとおりです。
| 目的 | private alpha | public beta | 移行時の注意 |
|---|---|---|---|
| Agent一覧 | GET /v1/agents |
POST /v1/agents/query |
クエリ条件をJSON bodyへ移す |
| 会話一覧 | GET /v1/agents/:agent_id/threads |
POST /v1/sessions/query |
agent_idはfilterへ移す |
| メッセージ履歴 | GET /v1/threads/:thread_id/messages |
POST /v1/sessions/:session_id/events/query |
返答はagent.messageイベントから読む |
| 会話開始・継続 | POST /v1/agents/:agent_id/chat |
POST /v1/sessions |
agent_idまたはsession_idをbodyへ入れる |
| リアルタイム応答 | POST /v1/agents/:agent_id/chatStream |
POST /v1/sessionsとSSE |
NDJSONではなくSSE envelopeを解析する |
Sessionの状態は7種類を前提にする
statusはqueued、in_progress、requires_action、completed、failed、canceled、terminatedの7種類です。既知の終端状態だけを明示し、未知の値は非終端として扱うのが公式の推奨です。
Messageの文字列ではなくEventのcontent partsを読む
返答はagent.messageイベントのcontent配列に入ります。type: textを順番に連結し、失敗はSessionのerrorとsession.statusから取得します。
Sessions APIを動かす4つの処理
以下は公式QuickstartとAPI Referenceに合わせたcURLです。macOS／LinuxのcURL 8系、Notion-Version: 2026-03-11を想定し、2026年8月28日に照合しました。
実行上の注意：本番へ入れる前に、権限を絞ったテスト用Custom Agentで確認してください。トークンは環境変数に置き、ログやクライアントへ出さないでください。
処理1：Agentを選んでSessionを開始する
POST /v1/agents/queryへ検索語とpage_sizeを送り、返されたidをAGENT_IDへ保存します。Session開始時はsession_idを省略します。
curl -X POST "https://api.notion.com/v1/sessions"
-H "Authorization: Bearer ${NOTION_API_KEY}"
-H "Notion-Version: 2026-03-11"
-H "Content-Type: application/json"
--data "{
"agent_id": "${AGENT_ID}",
"message": "経費精算の申請手順を要点で教えてください。"
}"続きの発言ではagent_idではなく、同じパスへsession_idと新しいmessageを送ります。
処理2：SSEで返答を受け取る
リアルタイム表示では同じリクエストにAccept: text/event-streamを加えます。JSON版とSSE版を両方実行すると二重送信になるため、どちらか一方を選びます。
curl --no-buffer -X POST "https://api.notion.com/v1/sessions"
-H "Authorization: Bearer ${NOTION_API_KEY}"
-H "Notion-Version: 2026-03-11"
-H "Accept: text/event-stream"
-H "Content-Type: application/json"
--data "{
"agent_id": "${AGENT_ID}",
"message": "今週のプロジェクト更新を要約してください。"
}"| SSE envelope | 意味 | クライアント側の扱い |
|---|---|---|
session.snapshot |
開始時点のSession状態 | session_idを保存する |
event.provisional |
生成途中で置き換わり得る出力 | 画面表示だけに使い、永続化しない |
event.committed |
確定済みのSession Event | Eventを取り出して保存・表示する |
stream.timeout |
処理は継続中だが接続が終了 | 最後の確定Eventから再接続する |
stream.end |
現在のturnが終了 | statusを見て完了または承認待ちへ進む |
stream.error |
turnが失敗 | code、message、retryableを記録する |
切断時は最後のevent.committed.event.idをcontinue_fromへ渡します。sequenceや暫定IDは使いません。
処理3：承認・拒否アクションを返す
requires_actionではrequired_actionsを読み、各action_idへapproveまたはrejectを返します。
curl -X POST "https://api.notion.com/v1/sessions"
-H "Authorization: Bearer ${NOTION_API_KEY}"
-H "Notion-Version: 2026-03-11"
-H "Content-Type: application/json"
--data "{
"session_id": "${SESSION_ID}",
"actions": [
{"action_id": "${ACTION_ID}", "option_id": "approve"}
]
}"変更系actionは自動承認せず、操作者・対象・内容をUIに表示し、選択結果を監査ログへ残します。
処理4：Event履歴をページングする
履歴はQuery session eventsで取得します。回答だけならagent.messageへ絞り、sequence昇順にします。
curl -X POST "https://api.notion.com/v1/sessions/${SESSION_ID}/events/query"
-H "Authorization: Bearer ${NOTION_API_KEY}"
-H "Notion-Version: 2026-03-11"
-H "Content-Type: application/json"
--data '{
"filter": {
"property": "type",
"event_type": {"equals": "agent.message"}
},
"sorts": [{"property": "sequence", "direction": "ascending"}],
"page_size": 100
}'Eventは1回最大100件です。has_moreがtrueならnext_cursorを次のstart_cursorへ渡します。
Custom Agent管理APIを運用へつなげる
公開ベータには、利用可能なAgent、クレジット消費、停止を扱う管理APIもあります。
Query agentsで利用可能なAgentだけを出す
Query agentsはトークンから利用できるAgentを返し、名前・説明、ID、種別、作成日時、connectionで絞れます。管理画面の候補をAPI結果から作れば、共有解除や削除を反映できます。
権限不足のフィールドはhiddenになり得ます。credit limitの参照にはfull accessが必要なため、nullやhiddenも処理します。
Retrieve agent insightsで利用状況を見る
Retrieve agent insightsはGET /v1/agents/{agent_id}/insightsでtotal_credits_usedとruns_completedを返します。期間を省略すると現在のbilling periodが対象です。
Slack側の指標と結合すれば、重複Sessionなどを発見できます。ただしクレジット量だけで効果を断定せず、回答完了率、再質問、エスカレーションも見ます。
Batch manage agentは非同期かつ非アトミック
Batch manage agentはPOST /v1/agents/batchで、status、credit limit、削除を1〜100件まとめて非同期実行します。非アトミックなのでstatus_urlを確認し、結果のindexを元のoperationと突合します。
Slack botへ組み込む設計例
事例区分：想定シナリオ
以下は公開API仕様をもとにした社内FAQ botの設計例です。特定企業での導入実績や効果数値を示すものではありません。
Slack threadとNotion sessionを対応させる
Slackのteam_id、channel_id、thread_tsを会話キーにしてsession_idを保存します。初回だけagent_id、2回目以降は保存済みSessionを使います。
動作環境：Slack Events APIとNotion Agent APIをつなぐ言語非依存の擬似コード
// 注意: テスト用Agentとチャンネルで検証する
onSlackMessage(event):
key = event.teamId + ":" + event.channelId + ":" + event.threadTs
sessionId = sessionStore.find(key)
stream = sessionId
? continueNotionSession(sessionId, event.text)
: startNotionSession(agentId, event.text)
for item in stream.committedEvents:
if item.type == "agent.message": replyInThread(extractText(item.content))
sessionStore.save(key, stream.sessionId)Slack側の受信・署名検証・スレッド返信は別レイヤーに分けます。Slackアプリの基本実装は、既刊のSlack BoltとAIエージェントの統合実装ガイドで確認できます。
表示権限ではなくAgent権限を基準に監査する
Slack投稿者とCustom AgentのNotion権限は同じとは限りません。Agentが読める情報は、ページを直接開けない利用者にも回答経由で届く可能性があります。
- botを利用できるSlackチャンネルとユーザーをallowlistで限定する
- Custom AgentのTools and Accessを用途に必要なページだけへ絞る
- connection tokenを使い、利用対象のCustom Agentを明示する
- 機密情報を返す質問は人間の確認へエスカレーションする
- action承認画面に操作者、対象、予定される変更を表示する
SSE切断とレート制限を通常系として扱う
Request limitsは、connectionごとに平均3リクエスト/秒です。workspaceにはプラン別の共有上限もあり、429／529ではRetry-Afterを尊重します。
同時実行に備えてキュー、指数バックオフ、jitter、再試行上限を設け、SSEはcontinue_fromで再接続します。設計例はLLM APIのレート制限対策ガイドでも確認できます。
実装で止まりやすい5つの落とし穴
落とし穴1：検索で見つけたalphaコードを貼る
避けたい実装：alpha期のthreads／messages例や、chatStreamのNDJSON前提をそのまま採用する。
取るべき対応：2026年8月20日以降のdeveloper docsを正とし、@notionhq/clientまたは検証済みのHTTPリクエストでsessions／eventsへ移す。
落とし穴2：provisional出力を確定履歴として保存する
避けたい実装：event.provisionalをDBへ追記し、後から届く確定Eventも保存して二重表示を起こす。
取るべき対応：暫定出力は画面だけに表示し、永続化・通知・監査の対象はevent.committedに限定する。
落とし穴3：requires_actionを自動承認する
避けたい実装：応答速度を優先して、すべてのaction_idへ機械的にapproveを返す。
取るべき対応：副作用のある操作は人間へ提示し、承認者、対象、選択結果、Session IDを記録する。拒否時の分岐もテストする。
落とし穴4：Slack利用者の権限だけを見る
避けたい実装：投稿者が見られるページだけをAgentも見ると思い込み、共有チャンネルへ公開する。
取るべき対応：Custom Agent独自のアクセス範囲と、Agentを利用できる人の集合を照合する。機密度が異なる用途はAgentを分ける。
落とし穴5：ポーリングを無制限に続ける
避けたい実装：queued中に短い間隔でRetrieve sessionを呼び続け、複数ユーザーのアクセスで429を誘発する。
取るべき対応：可能ならSSEを使い、ポーリングする場合もキュー、間隔、最大試行回数を設定する。429と529ではRetry-Afterを読み、最終失敗を利用者へ返す。
9月30日までの移行チェックリスト
private alphaのagents、threads、messages、chatルートを使う場合、公式の移行期限は2026年9月30日です。日数ベースの計画ではなく、次の互換性チェックを完了条件にしてください。
- 旧ルート
GET /v1/agentsをPOST /v1/agents/queryへ変更した - Agent IDをURL pathではなくJSON bodyまたはfilterへ移した
thread_idをsession_idへ変更した- messagesの単一文字列ではなくEventのcontent partsを連結している
- NDJSON parserをSSE envelope parserへ置き換えた
event.provisionalとevent.committedを区別した- Sessionの7 statusとerrorオブジェクトを処理している
requires_action時のapprove／reject UIを用意した- Event履歴の
has_moreとnext_cursorを処理している - 429／529と
Retry-Afterをテストした - PATまたはconnection tokenの権限範囲を再確認した
- 旧ルートを使う監視、テスト、運用スクリプトも更新した
コード検索ではルート文字列だけでなく、thread_idやthread_messageなどの型名・永続化カラムも対象にしてください。API adapterだけを変えると、再接続や履歴参照に旧概念が残ります。
よくある質問
Notion Agent APIは誰でも今すぐ使えますか？
APIは2026年8月20日からpublic betaですが、Custom AgentsはBusiness／Enterprise向けです。利用者またはconnectionに対象Agentへのアクセスが必要なので、まずPOST /v1/agents/queryを確認します。
Notion Agent APIからCustom Agentを新規作成できますか？
できません。公式QuickstartはNotionアプリで作成済みのCustom Agentを前提とし、APIは検索、会話、利用状況、状態・上限管理に使います。
Notion AI Agent APIとNotion External Agent APIは同じですか？
方向が異なります。Notion Agent APIsはCustom Agentを外部アプリから呼び、External Agents APIは外部AgentをNotionへ参加させます。どちらの方向かを先に確定してください。
レート制限はいくつですか？
公式値はconnection単位で平均3リクエスト/秒です。workspace共有上限もあります。429／529ではRetry-After、指数バックオフ、jitterを使います。
Notion Agent APIの料金はいくらですか？
Agent APIリクエスト単体の料金表は公式Referenceで確認できません。Custom Agent実行はNotion creditsを消費し、Business／Enterprise向けadd-onは1,000 creditsあたり10米ドルです。消費量は処理で変わるため、料金ガイドとinsightsを確認してください。
公式SDKはどの言語に対応していますか？
Agent／Sessionメソッドを確認できる公式クライアントはJavaScript／TypeScriptの@notionhq/clientです。Referenceには複数言語のHTTP例もありますが、独立した公式SDKとは断定できません。他言語ではREST APIを直接呼びます。
Slack botではPATとconnection tokenのどちらが向いていますか？
個人検証はPAT、共有botは対象Agentを明示できるconnection tokenが管理しやすいでしょう。どちらでもAgentのTools and AccessとSlack利用者を別々に監査します。
参考・出典
- Notion Docs Changelog — 2026年8月20日のpublic beta発表、9月30日の移行期限、8月27日のMCP Session tools（参照日：2026年8月28日）
- Notion Agent APIs Overview — 機能、認証、権限（参照日：2026年8月28日）
- Notion Agent APIs Quickstart — Agent検索とSession開始（参照日：2026年8月28日）
- Create or update a session — body、SSE、actions、status（参照日：2026年8月28日）
- Upgrading to public beta — routeとstream移行（参照日：2026年8月28日）
- Notion API Request limits — 制限と再試行（参照日：2026年8月28日）
- Custom Agents sharing and permissions — Agent権限（参照日：2026年8月28日）
- Custom Agent pricing — credits料金（参照日：2026年8月28日）
最後に確認すべきこと
Notion Agent APIの使い方で迷ったら、まず「既存Custom Agentを外部から呼ぶ」「会話はSession」「履歴はEvent」という3点へ戻ってください。public betaでは、開始・継続・ストリーミング・承認・履歴取得がPOST /v1/sessionsを中心にまとまり、管理APIで利用状況と停止線も作れます。
- 新規実装は
sessions／eventsを使い、alphaのthreads／messagesを持ち込まない - SSEは暫定Eventと確定Eventを分け、切断時は確定Event IDから再接続する
- Slack利用者ではなくCustom Agent自身のアクセス範囲を監査する
- private alpha利用者は2026年9月30日までに移行テストを終える
この記事を読んで導入イメージが固まってきた方へ
UravationではAIエージェント導入の研修・コンサルを行っています。
この記事はAIgent Lab編集部がお届けしました。
