2026년 10월 20일, Cursor가 Agent SDK를 일반 제공(GA, General Availability)했습니다. 변경 로그에는 'generally available today'라고 명시되어 있어 베타 버전이 아닙니다. 관련 문서도 공개되었습니다.
Agent SDK에서는 에이전트를 '코드 폴더(프로젝트)' 형태로 정의합니다. 생성부터 로컬 실행, eval을 통한 테스트, 배포까지의 전 과정을 CLI를 통해 일관되게 처리할 수 있습니다. 배포 대상은 Cursor 인프라 또는 자체 인프라 중 선택 가능합니다.
'PR 리뷰 봇을 만들었는데 동작 확인이 수작업으로 이루어진다', 'Slack이나 GitHub에서 구동되는 에이전트를 프롬프트와 함께 리포지토리로 관리하고 싶다'라는 분들은 한 번 확인해 볼 가치가 있습니다.
📌 영향을 받는 사용자
- PR 자동 리뷰, 자동 수정, 승인 봇을 직접 제작 및 운영하는 팀
- Slack / GitHub / cron 등에서 구동되는 사내 에이전트를 구축하려는 사람
- Claude Agent SDK 등 다른 에이전트 기반 시스템과 비교 검토 중인 사용자
- MCP 서버를 에이전트에 연결하여 사용하는 사용자
Agent SDK는 다음 5가지 요소로 구성됩니다.
개발 흐름은 다음과 같습니다.
| 항목 | 내용 | 중요도 |
|---|
| Agent SDK GA | 에이전트를 코드 폴더로 정의하고, eval을 통해 테스트한 후 Cursor 또는 자체 인프라에 배포 | high |
| CLI | init / dev / --template을 이용한 생성 및 로컬 실행 | medium |
| 배포 (Deployment) | agent-sdk deploy를 사용하여 빌드, URL 발급, 구동까지 일괄 실행 | medium |
| 폴더 규약 | instructions.md ・tools/ ・skills/ ・mcp-connections/ ・channels/ | medium |
| Channels | Git 호스팅 / Slack / Webhook / cron을 통해 구동 | medium |
| Evals | agent-sdk eval 및 agent-sdk github replay | medium |
npx @cursor/agent-sdk init ./my-bot 명령어로 새로운 에이전트 프로젝트를 생성합니다. agent-sdk dev를 실행하면 플레이그라운드가 포함된 상태로 봇이 로컬에서 구동됩니다.
--template을 통해 선택할 수 있는 템플릿은 총 4가지입니다.
- 보안 리뷰어 (Security Reviewer)
- owners-policy(오너 정책) 승인 봇
- PR 자동 수정 봇
- Linear 또는 Jira의 트리아지 봇
에이전트는 하나의 프로젝트로, 다음 규약에 따라 구성됩니다.
| 경로 | 역할 |
|---|
instructions.md | 프롬프트 본문 |
tools/ | 파일 하나가 모델이 호출할 수 있는 타입 지정 액션 1개에 대응 |
skills/ | 모델이 필요에 따라 읽어들이는 절차 (Procedure) |
mcp-connections/ | MCP 서버로부터 도구 추가 |
channels/ | 봇이 메시지를 받고 응답하는 장소를 정의 |
agent-sdk validate를 통해 구성을 확인할 수 있으며, agent-sdk info를 사용하면 감지된 구성 요소를 목록으로 볼 수 있습니다.
💡 팁
프롬프트, 도구, 절차(Procedure), 외부 연결이 모두 파일로 분리되어 있습니다. 따라서 Git에서 차이점 리뷰(diff review)가 용이하며, PR 단위로 에이전트의 동작 변경을 관리할 수 있습니다.
구동의 계기는 다음과 같습니다.
| 트리거 | 내용 |
|---|
| GitHub / GitLab / Bitbucket | pull request, 댓글, CI 이벤트 |
| ... | |
꼭 알아두어야 할 점은 다음 세 가지입니다.
- GitHub 이벤트는 Cursor 계정을 통해 가져옵니다. 공개 Webhook URL을 별도로 준비할 필요가 없습니다.
- Slack은 기본적으로 충분히 지원됩니다.
- 대화마다 독립된 세션과 모든 메시지 및 모든 도구 호출 기록이 완벽하게 유지됩니다. 동일한 PR이나 Slack 스레드에서의 후속 조치는 같은 세션을 재개합니다.
프로젝트 디렉토리에서 agent-sdk deploy를 실행하면 빌드, URL 할당, Cursor 인프라 상에서의 구동까지 한 번에 처리합니다. 시크릿과 연동(integrations)은 대시보드에서 관리합니다. 배포 후에도 로컬 환경과 동일한 로그, 평가(eval), 플레이그라운드를 그대로 사용할 수 있습니다. 자체 인프라로의 배포도 가능합니다.
eval은 고정 메시지를 봇에게 보내 다음 내용을 검증합니다.
- 어떤 도구(tool)가 실행되었는지
- 그 도구의 입력이 무엇인지
- 응답이 어떤 형태인지
agent-sdk eval은 로컬 환경과 CI(지속적 통합) 모두에서 실행할 수 있습니다.
agent-sdk github replay <pr-url>은 실제 풀 리퀘스트(pull request)를 서명된 웹훅 페이로드로 변환하여 봇에게 전송합니다. 따라서 GitHub 기반의 봇을 푸시(push)를 기다리지 않고도 테스트할 수 있습니다. --dry-run --fixtures-dir fixtures/ 옵션을 추가하면, 페이로드를 전송하지 않고 eval용 피규어(fixture)로 저장합니다.
⚠️ 참고: 파괴적 변경은 아닙니다
이번에는 신기능의 추가이며, 기존 Cursor 사용에 필수적으로 대응해야 할 사항은 없습니다(action_required: false).
- 템플릿으로 시도하기: 4가지 유형 중 현재 과제와 유사한 것(예: PR 자동 수정)을 골라
init과 dev를 시도합니다.
- 기존 봇 정리: 이미 자체 제작한 봇이 있다면,
instructions.md/tools//skills/로 분리했을 때 어떻게 되는지 검토합니다.
- eval을 CI에 통합하기:
agent-sdk eval은 로컬 환경과 CI 모두에서 작동합니다.
- replay로 피규어 축적하기: 실제 PR로부터
--dry-run --fixtures-dir fixtures/를 사용하여 저장해 두면, 회귀 테스트의 자료가 됩니다.
- 배포처 결정하기: Cursor 인프라 또는 자체 인프라 중 시크릿 관리나 사내 정책 관점에서 선택합니다.
- MCP 연결 정리하기:
mcp-connections/에 MCP 서버를 배치하는 구성이 되므로, 기존 MCP 사용과의 관계를 확인해야 합니다.
에이전트를 폴더 구조로 정의한다는 발상은 Claude Agent SDK를 사용할 때의 설계와 비교할 수 있습니다. 선택할 때는 다음 관점에서 비교해 보는 것이 좋습니다.
- 정의 방식
- 테스트 수단 (eval / replay)
- 배포처
- 트리거 유형
# 신규 에이전트 프로젝트 생성
npx @cursor/agent-sdk init ./my-bot
# 플레이그라운드와 함께 로컬 구동
...
my-bot/
├── instructions.md # 프롬프트 본문
├── tools/ # 1파일 = 타입이 지정된 액션 1개
...
파일 내부 내용(tools의 기술 형식 등)은 이번 정보에는 포함되어 있지 않습니다. 자세한 내용은 공식 문서를 확인해 주십시오.
# 구성 검증
agent-sdk validate
# 감지된 구성 요소를 일람 표시
...
Before: 수동 확인
1. 봇 수정
2. 검증용 PR을 만들고 푸시
3. 웹훅이 도착하는 것을 기다림
...
After: eval과 replay
# 고정 메시지로, 도구/입력/응답의 형태를 검증 (로컬/CI)
agent-sdk eval
# 실제 PR을 서명된 웹훅 페이로드로 변환하여 봇에게 전송
...
Changelog 페이지에서 2026년 9월 10일 자 Cursor Projects (베타) 항목이 사라졌습니다.
- 신규 항목(Agent SDK) 추가와 동시에 사라진 것으로 보이며, 표시 개수 제한으로 인한 밀림 현상으로 추정됩니다.
Projects 기능 폐지를 나타내는 설명은 없습니다.
Projects를 사용하고 있더라도, 이 사안만으로 당황하여 대응할 필요는 없습니다. 걱정된다면 앱 내 기능이나 문서를 통해 현재 상태를 확인해 주십시오.
- Cursor Agent SDK가 2026년 10월 20일 GA가 되었습니다. - 에이전트를
instructions.md/tools/
/skills/
/mcp-connections/
/channels/
의 폴더 구조로 정의합니다.
init → dev → validate → eval → deploy
흐름에 따라, 생성부터 배포까지 CLI(Command Line Interface)에서 완료됩니다. - Channels를 통해 GitHub / GitLab / Bitbucket / Slack / Webhook / cron 등으로부터 시작할 수 있습니다. GitHub의 이벤트는 Cursor 계정을 경유하기 때문에 공개 Webhook URL은 필요하지 않습니다.agent-sdk github replay를 사용하면 실제 PR을 이용한 테스트가 푸시 없이 가능합니다. - 배포 대상은 Cursor 인프라와 자체(Self-hosted) 인프라 중 선택할 수 있습니다.- 필수적으로 대응해야 할 사항은 없습니다. 먼저 템플릿을 사용하여 작게 시도해 보는 것을 권장합니다.
- Changelog에서 Projects 항목이 사라진 것은 표시 범위의 변화로 보입니다.
