Notion Agent APIの使い方｜Sessions実装4手順

月曜朝、Slackの質問スレッドから社内規程を知っているCustom Agentを呼び出そうとして、古いサンプルのthread_idをどこへ渡すのか分からず手が止まる。

Notionの公式ページにはalpha期のAgent SDK表記も残っているため、検索で見つけたコードをそのまま使うと、現在のsessionsと噛み合わないことがあります。

このつまずきを解消する鍵が、2026年8月20日に公開ベータとなったNotion Agent APIsと、新しいSessions／Eventsモデルです。

APIパス、制限、料金、SDKの範囲を2026年10月1日時点の一次情報で再確認し、実装と移行に必要な点へ絞って整理します。

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実装5ステップで確認できます。

リクエスト前にそろえる3つの前提

Custom AgentはNotionアプリで先に作る

Sessions APIはCustom Agentを新規作成しません。公式Quickstartも既存Agentを前提とし、一覧から得たidをagent_idへ渡します。

Custom Agentsは2026年10月1日時点でも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-11
• Content-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年10月1日に公式ドキュメントを再確認しました。

実行上の注意：本番へ入れる前に、権限を絞ったテスト用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エージェント統合実装ガイド2026で確認できます。

表示権限ではなく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利用者を別々に監査します。

運営元 Uravation よりAIエージェントを構想から本番運用まで進める順番と、体制・KPIの決め方をまとめた資料を無料で公開しています。 AIエージェント導入ロードマップを受け取る（無料）

参考・出典

• 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利用者は、期限後の残存alphaルートがないことを確認し、public betaで移行テストを完了する

この記事はAIgent Lab編集部がお届けしました。

このテーマの関連記事

• ▸ 【2026年10月】LM Studio Bionicの日本語化｜設定と注意点
• ▸ n8n AI Agent入門｜ノード基本編【2026年10月】
• ▸ LangGraph MCP連携3手順【2026年10月4日】
• ▸ ローカルLLM×RAGの作り方｜オフライン実装【2026年10月】
• ▸ LangGraph Studioの使い方｜可視化・デバッグ【2026年10月】