Cursor Agent SDK로 코드 기반 에이전트 구성 방법을 확인해보세요

햇빛 드는 오크 책상 위 흐린 화면의 노트북과 나무 블록, 작은 화분과 컵, 노트와 스마트폰

프로젝트는 어떻게 시작하지?

현재 Agent SDK 공식 문서는 Node.js 22.13 이상과 @grok/agent-sdk 패키지를 안내한다. 설치와 로그인 방법은 이 문서에서 확인한 뒤, agent-sdk init ./my-bot으로 프로젝트를 만들고 프로젝트 폴더에서 agent-sdk dev를 실행하면 로컬 플레이그라운드가 뜬다.

10월 20일 변경 이력에는 @cursor/agent-sdk를 쓰는 초기화 예시가 있다. 현재 문서의 패키지 이름과는 다르다. 변경 이력은 초기화할 때 --template 옵션으로 보안 리뷰어, 소유자 정책 승인, PR 자동 수정, Linear 또는 Jira 이슈 분류 템플릿을 고를 수 있다고 설명한다. 설치하기 전에 현재 문서에서 패키지와 접근 조건을 다시 확인하자.

에이전트의 지시와 도구는 어디에 두지?

Cursor는 instructions.md를 에이전트의 지시문이라고 설명한다. 모델이 호출할 타입 지정 작업은 tools/에, 필요할 때 불러올 절차는 skills/에 둔다. mcp-connections/는 MCP 서버 도구를 연결하고, channels/는 메시지를 받거나 응답하는 경로를 정의한다.

프로젝트 구조는 agent-sdk validate로 검사하고, 발견된 항목은 agent-sdk info로 볼 수 있다. 검사를 통과해도 연결한 서비스의 권한과 실제 작업 결과는 따로 확인해야 한다.

어떤 이벤트에 반응할까?

공식 안내에서 실행 계기로 드는 것은 GitHub·GitLab·Bitbucket의 풀 리퀘스트와 댓글, CI 이벤트다. Slack 멘션과 DM, 웹훅, cron 일정도 지원한다. GitHub 이벤트는 Cursor 계정으로 가져오니 공개 웹훅 URL이 필요 없다고 한다.

각 대화는 자체 세션을 유지하고 메시지와 도구 호출을 기록한다. PR이나 Slack 스레드에서 후속 질문을 하면 같은 세션으로 이어진다. 연결할 채널의 접근 권한이 업무에 필요한 범위인지 확인하자.

배포와 검증은 어떻게 하지?

로컬 테스트에서는 agent-sdk eval로 고정 메시지를 보내 도구 호출과 응답 형태를 검증해 볼 수 있다. GitHub PR로 하는 테스트에는 agent-sdk github replay <pr-url>이 안내돼 있다. --dry-run --fixtures-dir fixtures/ 옵션은 페이로드를 평가용 픽스처로 저장한다.

Cursor에 배포할 준비가 되면 프로젝트 디렉터리에서 agent-sdk deploy를 실행한다. Cursor 설명으로는 이 명령이 프로젝트를 빌드하고 URL을 붙여 Cursor 인프라에서 돌려 준다. 시크릿과 연동은 대시보드에서 관리한다.

배포 전에 에이전트가 호출할 도구 목록과 권한을 확인하자. 로컬 평가에서는 허용한 작업과 응답 형태가 의도대로인지 점검하자. 변경 이력은 2026년 11월 2일에 확인했다.