Cursor의 기능과 실용적인 사용법
🧩 커서(Cursor)의 AI 에이전트를 자체 스크립트나 CI 체크 과정에서 호출할 수 있다면 어떨까요? @cursor/sdk는 이러한 염원을 실현하는 TypeScript 기반의 에이전트 조작 인터페이스입니다.
🏷️ 제목: @cursor/sdk(TypeScript)
🔗 URL: https://t.co/5AS4itMn0Q
📘 개요
@cursor/sdk는 IDE, CLI, 웹 앱에서 사용되는 것과 동일한 Cursor 에이전트를 스크립트 가능한 TypeScript 인터페이스로 공개하는 패키지입니다. CI 자동화, 제품에의 통합(embedding), 독자적인 워크플로우 오케스트레이션 등에 사용할 수 있습니다. Node를 전제로 하며, 로컬 실행용 코드는 지연 로드되므로 클라우드 전용 사용 시에는 시작 비용이 발생하지 않습니다.
⚙️ 기능 설명
주요 개념은 Agent(대화 문맥과 워크스페이스 설정을 유지하는 상태 저장 컨테이너), Run(1회 프롬프트 전송, 그 출력 스트림, 상태 및 결과), SDKMessage(실행 중에 흐르는 정규화된 이벤트)입니다.
Agent.create(): 옵션을 검증하고 즉시 핸들을 반환하며, agent.send()로 프롬프트를 보낼 수 있습니다.- local / cloud 키: 실행 장소를 전환합니다.
local은 사용자의 Node 프로세스 내에서 에이전트 루프를 돌리고, cloud는 Cursor 호스트의 격리된 VM에서 리포지토리를 가져와 구동합니다(자체 VM 풀도 가능).
- 'local'은 에이전트 루프가 위치하는 곳만을 의미하며, 모델 추론은 두 모드 모두 Cursor 백엔드를 통해 이루어집니다.
local.customTools를 사용하여 독자 함수를 툴로 전달할 수 있습니다(로컬 전용). Agent.prompt()는 원샷(one-shot) 용의 단축키입니다.
🛠️ 실용적인 사용법
설치는 스코프가 지정된 정확한 이름인 npm install @cursor/sdk가 필요합니다.
로컬 작업 트리에 대해 CI 체크를 실행하려면, Agent.create()에 apiKey, https://t.co/U2NL19xigZ, local.cwd를 전달하고, agent.send()로 프롬프트를 보내 run.wait()의 status가 finished인지 판별합니다. 완료되면 agent[Symbol.asyncDispose]()로 뒷정리를 합니다.
클라우드 실행으로 전환하려면 cloud 키를 사용하고, autoCreatePR: true로 설정하여 완료 시 PR을 열 수 있습니다. 인증은 CURSOR_API_KEY 환경 변수 또는 apiKey 지정으로 하며, 사용자 키 또는 서비스 계정 키를 사용할 수 있습니다.
💡 유스케이스
PR의 CI에서 Agent.prompt()를 실행하여 보안 감사를 자동화하거나, cloud 키로 다수의 에이전트를 병렬로 구동하여 대규모 리팩토링을 별도의 브랜치에 PR할 수 있거나, local.customTools로 사내 배포 확인 API를 에이전트에 제공하여 자체 워크플로우에 통합하는 등의 사용이 가능합니다.
⚠️ 주의사항
로컬 모드는 샌드박스나 후크를 설정하지 않는 한, 쉘 실행이나 파일 편집을 승인 없이 수행합니다. CI에서는 local.sandboxOptions: { enabled: true }를 고려하십시오. Python SDK는 존재하지 않으며, Node가 아닌 언어에서는 SDK Bridge를 사용하거나 Cloud Agents의 REST API를 직접 호출해야 합니다. Agent.resume()에서는 인라인의 mcpServers가 손실되므로 재지정이 필요하며, 모델 ID는 변경될 수 있으므로 Cursor.models.list()로 확인하는 것이 안전합니다.
#Cursor #SDK
