튜토리얼2026년 11월 6일

Cursor Agent SDK 한눈에 보기: 에이전트를 폴더 하나로 정의하고 eval로 검사하기

진

진호AIPida 팀

@agent_woo

Cursor가 10월 20일 Agent SDK를 정식 출시했습니다. 에이전트를 코드 폴더로 정의하고, eval로 동작을 검사한 뒤, Cursor나 자체 인프라에 배포하는 도구입니다.

시작하기

npx @cursor/agent-sdk init ./my-bot
agent-sdk dev

dev를 실행하면 로컬 플레이그라운드에서 바로 대화해 볼 수 있습니다. --template을 붙이면 보안 리뷰어, 코드 소유자 정책 승인, PR 자동 수정, Linear·Jira 이슈 분류 템플릿에서 시작합니다.

에이전트 = 프로젝트 폴더

위치	역할
`instructions.md`	프롬프트
`tools/`	파일 하나가 모델이 호출하는 타입 지정 액션 하나
`skills/`	필요할 때 불러오는 절차
`mcp-connections/`	MCP 서버에서 가져오는 도구
`channels/`	메시지를 받고 답하는 곳

agent-sdk validate로 구성을 검사하고, agent-sdk info로 인식된 구성 요소를 확인합니다.

언제 깨어나나

GitHub·GitLab·Bitbucket의 PR, 댓글, CI 이벤트
Slack 멘션과 DM
임의 서비스의 웹훅, cron 일정

GitHub 이벤트는 Cursor 계정을 거쳐 들어오므로 공개 웹훅 주소가 필요 없습니다. 대화마다 세션이 따로 유지되고, 같은 PR이나 Slack 스레드에서 이어 말하면 그 세션이 다시 열립니다.

eval로 검사하기

eval은 정해 둔 메시지를 보내고 어떤 도구를 어떤 입력으로 불렀는지, 답의 형태가 맞는지를 확인합니다. 로컬이나 CI에서 agent-sdk eval로 돌립니다.

agent-sdk github replay <PR 주소>는 실제 PR을 서명된 웹훅으로 바꿔 봇에 보내므로, 푸시를 기다리지 않고 GitHub 봇을 시험할 수 있습니다. --dry-run --fixtures-dir fixtures/를 붙이면 그 내용을 eval 자료로 저장합니다.

배포

프로젝트 폴더에서 agent-sdk deploy를 실행하면 Cursor 인프라에 올라가고 주소가 생깁니다. 비밀값과 연동은 대시보드에서 관리하고, 로그·eval·플레이그라운드는 로컬과 같은 방식으로 씁니다.

이런 팀에 맞습니다

PR 리뷰·라벨링·이슈 분류처럼 반복되는 저장소 작업을 봇에 맡기려는 팀
프롬프트를 바꿀 때마다 동작이 달라질까 걱정돼 테스트부터 갖추고 싶은 팀

반대로 한 번 쓰고 말 자동화라면 기존 워크플로 도구가 더 빠를 수 있습니다.