2026년 11월 2일, Notion Agent APIs의 베타 기간이 종료되고 일반 제공(GA)이 시작되었습니다. 이는 프로덕션 환경에서 Agent APIs를 사용하여 연동을 구축할 수 있는 전제 조건이 마련되었다는 의미입니다.
다만, GA가 되었다고 해서 단순히 '새로운 기능이 추가된' 것만이 아닙니다. 동시에 다음과 같은 변경 사항들이 함께 적용됩니다.
- 개인용 알파(Private Alpha)용 루트가 **사용 중단 권장(Deprecated)**되었습니다.
- 'Update agent status' 엔드포인트가 사용 중단 권장되었습니다.
- 개인 에이전트(Personal Agent, 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 | 불필요 |
| ... | PATCH /v1/agents/{agent_id} 추가 | 신규 기능 | medium |
| Update agent status 사용 중단 권장 | 사용 중단 권장 | medium | 필요 |
베타 기간이 끝나고 본 서비스 이용을 전제로 할 수 있는 상태가 되었습니다. 지금까지 '베타라서' 프로덕션 배포를 미루었던 팀이라면, 도입 재검토의 시점입니다.
⚠️ Breaking Change (호환성 깨짐)
개인용 알파 기간에 사용했던 루트는 더 이상 권장되지 않습니다. 마이그레이션 경로는 공식 가이드 'Upgrading from the alpha routes'에 명시되어 있습니다. 폐지일은 이번 변경 사항에는 기재되어 있지 않으나, 이미 사용 중단 권장 상태이므로 빠른 전환이 바람직합니다.
알파 시절부터 검증용 스크립트나 사내 도구를 구동해 왔다면, 인지하지 못한 사이에 사용 중단 권장 루트를 계속 호출하고 있을 가능성이 있습니다.
개인 액세스 토큰(Personal Access Token)을 사용하여 agent_id에 notion_ai를 지정하면 개인 에이전트를 조작할 수 있습니다.
상세한 대응 방법은 공식 문서 'The personal agent'를 참조해 주십시오.
사용 사례 예시
- 사내 포털이나 채팅 도구에서 자신의 Notion AI에 문의하기
- 용도에 따라 사용할 모델을 스크립트로 전환하기
- 에이전트의 인사이트를 가져와 이용 현황 확인하기
name, description, model, status, favorite 속성을 단 한 번의 요청으로 일괄 업데이트할 수 있습니다. 이전에는 항목별로 분리되어 있던 업데이트 작업들을 통합할 수 있게 되었습니다.
⚠️ 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와 개인 액세스 토큰으로 호출할 것
【선택】신규 기능 검증: 개인 에이전트 조작을 시도해 볼 것
💡 팁
만약 AI 코딩 에이전트(Claude Code 등)에게 Notion 연동 코드를 작성하게 하는 경우, 지침서에 오래된 정보가 남아 있으면 비권장 루트를 사용한 코드가 계속 생성됩니다. 따라서 지침서를 먼저 업데이트하는 것이 효과적입니다.
아래는 개념을 보여주는 예시입니다. 요청 본문(request body)의 정확한 스키마는 공식 문서("Update an agent", "The personal agent")에서 확인해 주십시오. 여기서 확실하게 말할 수 있는 것은, 엔드포인트 PATCH /v1/agents/{agent_id}, 업데이트 가능한 항목(name / description / model / status / favorite), 그리고 agent_id에 notion_ai를 지정할 수 있다는 점입니다. 기본 URL이나 헤더 등은 생략했습니다.
# "Update agent status" 엔드포인트를 호출 (비권장)
# 항목별로 다른 요청이 필요했음
PATCH /v1/agents/{agent_id}
Content-Type: application/json
{
...
