はじめに
2026年11月2日、Notion Agent APIs のベータが終了し、一般提供（GA）が始まりました。本番環境で Agent APIs を使う連携を作るための前提が整った、ということです。
ただし、GA は「新機能が増えた」だけの話ではありません。同時に次の変更が入っています。
- プライベートアルファ用ルートが非推奨になった
- 「Update agent status」エンドポイントが非推奨になった
- パーソナルエージェント（Notion AI）を
agent_id=notion_aiで操作できるようになった -
PATCH /v1/agents/{agent_id}が追加された
📌 影響を受ける人
- プライベートアルファ期間から Agent APIs を使っている人(アルファ用ルートの移行が必要)
- 「Update agent status」を呼び出しているコードを持つ人
- Notion AI を社内ツールや自動化から呼び出したい人
- Notion 連携の指示書(CLAUDE.md など)を管理している人
この記事では、優先度の高い順に「何が変わり、何をすべきか」を整理します。
変更の全体像
| 変更 | 種別 | 重要度 | 要対応 |
|---|---|---|---|
| Agent APIs が GA | 発表 | high | 不要 |
| アルファ用ルートが非推奨 | 非推奨 | high | 必要 |
| パーソナルエージェント操作 | 新機能 | high | 不要 |
PATCH /v1/agents/{agent_id} 追加 |
新機能 | medium | 不要 |
| Update agent status が非推奨 | 非推奨 | medium | 必要 |
変更内容
1. Agent APIs が一般提供（GA）に
ベータが終了し、本番利用を前提にできる状態になりました。これまで「ベータだから」と本番投入を見送っていたチームは、導入を再検討するタイミングです。
2. プライベートアルファ用ルートが非推奨に（要対応）
⚠️ Breaking Change
プライベートアルファ期間のルートは非推奨になりました。移行先は公式ガイド 「Upgrading from the alpha routes」 に記載されています。廃止日は今回の差分には記載されていませんが、非推奨になった以上、早めの移行が望ましいです。
アルファ時代から検証用スクリプトや社内ツールを動かしている場合、気づかないうちに非推奨ルートを呼び続けている可能性があります。
3. パーソナルエージェント（Notion AI）を API から操作可能に
パーソナルアクセストークンを使い、agent_id に notion_ai を指定すると、パーソナルエージェントを操作できます。
| # | できること |
|---|---|
| 1 | セッションの開始(チャット) |
| 2 | エージェント情報の取得 |
| 3 | エージェントのインサイトの読み取り |
| 4 | 名前の変更 |
| 5 | 使うモデルの変更 |
対応操作の詳細は公式ドキュメント「The personal agent」を参照してください。
ユースケース例
- 社内ポータルやチャットツールから、自分の Notion AI に問い合わせる
- 使うモデルを、用途に応じてスクリプトで切り替える
- エージェントのインサイトを取得して、利用状況を確認する
4. PATCH /v1/agents/{agent_id}（Update an agent）が追加
name、description、model、status、favorite を 1回のリクエストでまとめて更新できます。これまで項目ごとに分かれていた更新操作を統合できます。
5. 「Update agent status」が非推奨に（要対応）
⚠️ Breaking Change
エージェントのステータス専用の更新エンドポイントは非推奨です。今後はPATCH /v1/agents/{agent_id}にstatusを渡して更新します。廃止日は差分に記載されていません。
影響と対応
優先度の高い順のアクション
- 【必須】アルファ用ルートの棚卸し: コードベースから旧ルートの呼び出しを洗い出し、公式ガイドに沿って GA 版ルートへ置き換える
-
【必須】Update agent status の置き換え:
PATCH /v1/agents/{agent_id}にstatusを渡す形へ変更する -
【推奨】指示書の更新: Notion 連携のセクション(例: 「Notion API / 外部連携」)に次を反映する
- Agent APIs は 2026-11-02 に GA(ベータ扱いの記述は削除)
- アルファ用ルートは使わず GA 版ルートを使う
- エージェント属性の更新は
PATCH /v1/agents/{agent_id} - パーソナルエージェントは
agent_id=notion_aiとパーソナルアクセストークンで呼ぶ
- 【任意】新機能の検証: パーソナルエージェント操作を試す
💡 Tips
AI コーディングエージェント(Claude Code など)に Notion 連携コードを書かせている場合、指示書に古い情報が残っていると非推奨ルートを使ったコードが生成され続けます。指示書の更新を先に済ませると効果的です。
コード例
以下は 概念を示す例です。リクエストボディの正確なスキーマは公式ドキュメント(「Update an agent」「The personal agent」)で確認してください。ここで確実に言えるのは、エンドポイント
PATCH /v1/agents/{agent_id}、更新できる項目(name / description / model / status / favorite)、agent_idにnotion_aiを指定できる点です。ベース URL やヘッダーなどは省略しています。
Before: ステータス専用エンドポイント(非推奨)
# 「Update agent status」エンドポイントを呼ぶ(非推奨)
# 項目ごとに別のリクエストが必要だった
After: PATCH でまとめて更新
PATCH /v1/agents/{agent_id}
Content-Type: application/json
{
"name": "営業サポートAgent",
"description": "商談メモの要約を担当",
"status": "active",
"favorite": true
}
-
statusの値(上記の"active"など)は例示です。取り得る値は公式ドキュメントで確認してください - 複数項目を 1 リクエストで更新でき、リクエスト数を減らせます
パーソナルエージェントを対象にする場合
PATCH /v1/agents/notion_ai
Authorization: Bearer <パーソナルアクセストークン>
Content-Type: application/json
{
"name": "マイアシスタント"
}
名前の変更・モデルの変更が対応操作として挙げられています。PATCH でどこまで操作できるかは「The personal agent」で確認してください。
まとめ
- Notion Agent APIs が 2026-11-02 に GA。本番利用の前提が整った
- アルファ用ルートは非推奨。「Upgrading from the alpha routes」に従って移行する(廃止日は未記載のため早めに)
-
「Update agent status」も非推奨。
PATCH /v1/agents/{agent_id}にstatusを渡す -
agent_id=notion_aiとパーソナルアクセストークンで、パーソナルエージェントを API から操作できる - 非推奨対応とあわせて、CLAUDE.md などの指示書も更新しておく
まずは自分のコードに旧ルートや旧エンドポイントの呼び出しが残っていないかを確認するところから始めましょう。