TypeScript Agent SDK API

query()와 메시지 순회

TypeScript SDK는 @anthropic-ai/claude-agent-sdk 패키지의 query()를 중심으로 사용한다. query()의 반환값을 순회하면서 assistant 메시지는 사용자 화면에, tool 관련 이벤트는 작업 상태에, result 메시지는 완료·실패 처리에 반영한다. 메시지의 모든 필드를 고정된 사내 프로토콜처럼 가정하지 말고, 현재 SDK 레퍼런스의 타입을 사용한다.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "현재 프로젝트의 테스트 전략을 읽고, 수정 없이 요약해 주세요.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

이 예시는 읽기 전용 도구만 허용한다. 파일 변경이나 명령 실행이 필요한 작업에서는 필요한 도구와 작업 디렉터리를 좁게 추가하고, 승인 흐름을 생략하지 않는다.

Claude Code 기능을 SDK에 가져오기

Agent SDK는 CLI의 여러 기능을 공식 옵션으로 재사용한다. 어떤 기능이 SDK에서 가능한지와 CLI 전용인지를 구분해야 한다.

| 기능 | SDK 구성 방식 | 주의점 | | --- | --- | --- | | 프로젝트 지시사항 | settingSources로 프로젝트 설정을 로드 | 신뢰하는 작업공간만 포함 | | skills | settingSources와 skills 옵션 | 필요한 스킬만 명시적으로 선택 | | 서브에이전트 | agents 옵션과 Agent 도구 | 에이전트별 도구·역할을 제한 | | hooks | hooks 옵션 | 결정적 정책은 코드·정책으로 검증 | | MCP | mcpServers 옵션 | 서버의 권한·콘텐츠를 신뢰하지 않음 | | agent teams | CLI 전용 실험 기능 | SDK 옵션으로 구성하지 않음 |

공식 기능 맵은 agent teams를 Agent SDK 설정으로 제공하지 않는다고 구분한다. SDK 애플리케이션에서 팀 협업이 필요하면, 먼저 SDK 서브에이전트와 애플리케이션 수준의 작업 큐로 해결 가능한지 검토하고, CLI의 실험 기능을 SDK API로 추정하지 않는다.

Skills, hooks, MCP의 역할 분리

skills는 모델이 필요할 때 불러 쓰는 재사용 가능한 지침과 워크플로다. hooks는 특정 생명주기 이벤트에 결정적으로 반응하는 정책·자동화다. MCP는 외부 도구와 데이터 소스를 연결하는 프로토콜이다. 셋은 대체 관계가 아니므로 역할을 섞어 보안 정책을 숨기지 않는 편이 좋다.

사용 방법과 절차                → Skill
항상 실행할 검증·감사            → Hook
외부 시스템의 도구·데이터 연결    → MCP

예를 들어 배포 절차를 설명하는 내용은 skill에 두고, 배포 전에 비밀 파일을 차단하는 검사는 hook으로 두며, 이슈 관리 시스템 호출은 MCP 서버로 제공한다. 각 계층에 똑같은 권한 결정을 중복하지 않으면 검토와 장애 분석이 쉬워진다.

버전과 운영 검증

Agent SDK의 옵션과 타입은 릴리스에 따라 확장될 수 있다. 패키지 버전을 잠그고, SDK 타입 검사와 최소 권한 통합 테스트를 함께 실행한다. 특히 MCP 서버나 hook이 파일·네트워크·비밀에 접근한다면, 프롬프트 인젝션과 우회 경로를 포함한 실패 사례도 검증한다. 이 장의 예제는 공개 문서의 패키지와 옵션 이름을 사용하지만, 실제 배포 전에는 설치한 버전의 레퍼런스를 다시 확인해야 한다.