Notion’s Developer Platform

Notion’s Developer Platform이란?

Notion’s Developer Platform은 Notion을 공유 워크스페이스로 활용해 빌드할 수 있는 개발자 기능 세트입니다—외부 데이터를 Notion으로 동기화하고, Notion Agents가 사용할 수 있는 커스텀 도구를 만들며, 다단계 에이전트 워크플로를 구성합니다.

핵심 목적은 외부 시스템을 Notion에 연결하는 것(예: 다른 소스에서 Notion Database를 업데이트 유지)과 Notion Agents를 목적에 맞는 액션 및 도구 인터페이스로 확장하는 것입니다.

주요 기능

Workers를 사용해 외부 레코드를 Notion Database에 지속적으로 upsert하세요. 선언적 스키마와 영속 커서를 사용해 실행 간 업데이트를 재개할 수 있습니다.
외부 데이터셋을 Notion으로 예약 동기화(예: 5m 같은 동기화 일정 정의).
Notion Agents용 커스텀 에이전트 도구로 출력(예: 자산)을 생성하고 외부 API나 실시간 데이터와 상호작용합니다.
구조화된 도구 인터페이스로 도구의 입력 스키마를 정의(예: 프레젠테이션 생성을 위한 pageId 문자열, 또는 웨어하우스 쿼리 실행을 위한 SQL query 문자열).
웹훅 기반 워크플로 오케스트레이션으로 다른 앱의 수신 웹훅을 듣고 Notion Agents, 페이지, 데이터베이스, 외부 API 호출로 Notion 워크플로를 트리거합니다.

Notion’s Developer Platform 사용 방법

Notion Database를 생성하거나 대상으로 지정하고 해당 데이터베이스와 외부 데이터 필드 간 스키마 매핑을 정의하세요.
데이터 동기화를 위한 Worker 빌드: 관리형 데이터베이스 연결을 구성하고 초기 스키마/기본 키를 제공하며, 레코드 변경을 반환하는 동기화 함수를 작성하세요(예: 소스 필드를 Notion 속성으로 매핑).
동기화 일정과 안정적 식별자(기본 키)를 설정해 레코드가 중복되지 않고 upsert되도록 하세요.
선택적으로 Notion Agents용 커스텀 도구 추가: 도구 이름, 설명, 입력 스키마, 액션을 수행하는 실행 핸들러로 도구를 등록하세요(예: Notion 페이지에서 .pptx 자산을 생성해 페이지에 업로드).
이벤트 기반 자동화가 필요하다면, 에이전트와 외부 API 호출로 Notion 워크플로를 트리거하는 웹훅 리스너를 구성하세요.

사용 사례

Notion으로 지원 티켓 수집: Worker를 사용해 외부 헬프데스크의 티켓을 Notion Database로 지속 동기화하며, 티켓 ID로 upsert하고 제목, CSAT, 태그 등의 필드를 매핑합니다.
Notion 콘텐츠에서 자동 자산 생성: Notion 페이지를 마크다운으로 읽고 제목을 슬라이드로 변환해 생성된 .pptx를 업로드하고 페이지에 추가하는 커스텀 도구(예: createPresentation)를 만듭니다.
에이전트 도구로 데이터 웨어하우스 쿼리: SQL 쿼리 문자열을 받아 웨어하우스 테이블에서 실행하고 결과를 에이전트 워크플로에 반환하는 도구(예: queryRevenue)를 정의합니다.
외부 이벤트로 트리거되는 액션 워크플로: 모든 앱의 이벤트를 듣고 Notion Agents를 사용해 페이지/데이터베이스와 외부 API 호출로 Notion 워크플로를 실행하는 웹훅 기반 워크플로를 빌드합니다.
에이전트 도구로 제어하는 브라우저 기반 앱 액션: 브라우저 자동화 제공자를 사용해 외부 앱에서 다단계 작업을 실행하는 에이전트 도구를 구현합니다(예: 저장된 식사 목록 확인, 주문 확인, 배송 상태 확인).

자주 묻는 질문

플랫폼이 Notion 데이터베이스를 지속적으로 동기화하나요?

네. 예시에서 영속 커서를 사용해 외부 레코드를 Notion Database에 지속적으로 upsert하는 Worker를 설명합니다.

커스텀 도구가 생성할 수 있는 출력은 어떤 것인가요?

제공된 예시에는 Notion 페이지 콘텐츠에서 PowerPoint(.pptx)를 생성해 페이지에 업로드하는 것이 포함됩니다.

에이전트 도구가 실시간 외부 시스템을 쿼리할 수 있나요?

네. 한 예시 도구는 딜 웨어하우스 테이블에 SQL 쿼리를 실행하며, 다른 예시는 브라우저 자동화로 외부 앱 액션을 사용합니다.

이벤트 기반 자동화는 어떻게 작동하나요?

페이지에서 모든 앱의 수신 웹훅을 듣고 Notion Agents, 페이지, 데이터베이스, 외부 API 호출을 사용하는 Notion 워크플로를 실행하는 것을 설명합니다.

Notion에 레코드를 upsert하려면 무엇이 필요하나요?

예시에서 스키마와 기본 키 속성을 가진 관리형 데이터베이스 연결을 정의하고, 외부 레코드를 Notion 속성으로 매핑하는 동기화 함수를 제공합니다.

대안

범용 ETL/ELT 도구 (데이터 동기화 전용): 주요 목표가 데이터를 데이터베이스로 이동하고 변환하는 것이라면, ETL 도구가 주기적 수집을 처리할 수 있지만, Notion Developer Platform은 에이전트 도구와 워크플로 오케스트레이션도 지원합니다.
워크플로 자동화 플랫폼 (트리거 및 오케스트레이션용): 이 카테고리의 도구는 웹훅과 앱 간 액션을 조정할 수 있지만, Notion 페이지와 데이터베이스에서 작동하는 Notion Agents와의 긴밀한 결합을 제공하지 않을 수 있습니다.
외부 통합이 있는 에이전트 도구 프레임워크 (커스텀 도구 호출용): 이미 에이전트 시스템을 구축 중이라면, 도구 프레임워크를 사용해 API를 호출하고 자산을 생성할 수 있습니다; Notion의 플랫폼은 Notion 워크스페이스 주변의 에이전트 상호작용과 데이터 동기화에 특화되어 있습니다.