Claude Code SDK에서 Claude Agent SDK로: 헤드리스 AI 에이전트 만들기

Claude Code SDK에서 Claude Agent SDK로: 헤드리스 AI 에이전트 만들기

터미널에서 쓰던 Claude Code를 화면 없이, 코드 안에서 부르고 싶었던 적 있으신가요? 바로 그걸 가능하게 하는 게 Claude Code SDK입니다. 2025년 5월 22일 Anthropic의 첫 개발자 컨퍼런스 'Code with Claude'에서 소개됐고, 지금은 Claude Agent SDK라는 이름으로 더 넓어졌습니다. 이 글에서는 헤드리스 AI 에이전트가 무엇인지, 어디에 쓰는지, 그리고 발표 당시 "곧 나온다"던 기능들이 2026년 7월 현재 어떻게 정식 출시됐는지 정리했습니다.

Claude Code SDK란 무엇인가요?

**Claude Code SDK(현 Claude Agent SDK)**는 Claude Code 에이전트를 화면 없이(헤드리스로) 코드에서 직접 부르는 도구입니다. 터미널로 bash를 실행하고 파일을 읽고 고칠 수 있는 "컴퓨터를 쥔 AI"를 여러분의 스크립트, CI, 챗봇에 끼워 넣을 수 있습니다.

Anthropic 엔지니어 Sid Bidasaria는 발표에서 이걸 "새로운 종류의 빌딩 블록"이라고 표현했습니다. 지금까지 만들 수 없던 애플리케이션을 만들 수 있게 해주는 기본 부품이라는 뜻이죠.

핵심 철학은 하나입니다. "에이전트에게 컴퓨터를 줘라(give agents a computer)." 사람이 컴퓨터로 일하듯, AI에게 터미널과 파일 시스템을 쥐여주면 코딩만이 아니라 CSV 분석, 웹 검색, 데이터 시각화, 지표 해석 같은 범용 작업까지 스스로 해냅니다.

헤드리스 모드란 무엇인가요?

'헤드리스(headless)'는 화면 UI 없이 프로그램처럼 돌린다는 뜻입니다. 평소 Claude Code는 대화창을 열고 주고받지만, 헤드리스 모드는 명령어 한 줄로 결과만 받아옵니다.

핵심 플래그는 -p(또는 --print)입니다. 이걸 붙이면 대화창 없이 실행하고 최종 답만 출력합니다. 게다가 표준 입력(stdin)을 읽기 때문에 유닉스 파이프와 그대로 이어집니다.

ifconfig -a | claude -p "이 네트워크 설정을 쉽게 설명해줘"

발표에서 Sid가 든 예시가 딱 이겁니다. "나는 아직도 ifconfig 출력을 못 읽겠는데, Claude는 읽는다"면서요. 로그 파일도 마찬가지입니다. cat app.log로 로그를 뽑아 그대로 넘기면 실패 원인을 요약해 줍니다.

여기서 SDK를 진짜 도구답게 만드는 옵션이 하나 더 있습니다.

claude -p "..." --output-format stream-json --verbose

--output-format json을 주면 답을 평범한 텍스트가 아니라 JSON으로 내보냅니다. 이 JSON에는 응답뿐 아니라 비용(total_cost_usd), 세션 ID, 진행한 턴 수 같은 정보가 들어 있어서, 다른 프로그램이 그걸 파싱해 위에 뭔가를 더 쌓아 올릴 수 있습니다. stream-json은 이걸 실시간 스트리밍으로 받는 방식이고요. 이 모든 게 지금은 공식 문서로 확립돼 있습니다.

헤드리스 SDK, 어디에 쓰나요? (4대 활용처)

발표 슬라이드는 활용처를 네 갈래로 나눴습니다. 흥미로운 건, 당시 "이런 걸 만들 수 있다"던 그림이 2026년 7월 현재 전부 공식 기능으로 실현됐다는 점입니다.

1. 스크립트와 유닉스 파이프라인

claude -p를 bash가 도는 곳 어디든 끼워 넣습니다. 파이프로 넣고 빼고 체인으로 엮습니다. --output-format json으로 비용까지 추적하면서요.

2. CI와 자동화

코드 리뷰를 Claude에게 맡기는 겁니다. 어떤 팀은 프로그램으로 정의하기 어려운 규칙을 위해 Claude에게 린터(코드 검사기)를 직접 짜게 시키기도 합니다.

3. 원격(remote) 환경

별도의 원격 환경에서 Claude가 코드를 쓰게 만드는 애플리케이션입니다. 지금은 Agent SDK 호스팅과 AWS Bedrock, Google Vertex AI, Microsoft Foundry 지원으로 실현됐습니다.

4. 웹 챗봇 코딩 인터페이스

Claude Code로 움직이는 나만의 챗봇을 만드는 것도 가능합니다. Agent SDK의 세션, 스트리밍, 커스텀 툴, MCP 서버 연결이 이 자리를 채웁니다.

@claude GitHub Actions: 실제 흐름은 이렇습니다

발표에서 가장 인상적인 부분은 라이브 데모였습니다. 오픈소스 퀴즈 앱을 하나 띄워 놓고, GitHub 이슈에 이렇게 댓글을 답니다.

"@claude please implement this feature"

그러면 4~5초 뒤 Claude가 "분석하고 다시 알려드릴게요"라고 답글을 달고, 브랜치를 만들어 기능을 구현하기 시작합니다. 할 일 목록(to-do list)을 스스로 만들어 하나씩 처리하고, 이슈 구현과 함께 열려 있던 풀 리퀘스트 리뷰까지 굴립니다.

이 @claude GitHub Action은 SDK 위에 만들어진 것입니다. 발표 표현대로 "SDK로 뭘 할 수 있는지 보여주는 영감의 원천"이죠. 지금은 공식 액션 anthropics/claude-code-action@v1으로 정식 출시됐습니다. 표준 GitHub Actions 러너 안에서 Claude Code 런타임 전체가 돌기 때문에 파일 읽기, git 조작, 코드 편집, 의존성 설치, 커밋 푸시까지 됩니다. 코드를 읽기만 하는 정적 리뷰 도구와는 결이 다릅니다.

작동 방식은 두 가지입니다.

• 대화형 모드: PR이나 이슈에서 @claude 멘션을 감지해 요청을 실행합니다. 데모의 그 흐름 그대로입니다.
• 자동화 모드: 워크플로 YAML에 prompt를 직접 적어두면, PR이 열리거나 CI가 실패할 때마다 헤드리스로 자동 실행됩니다.

설치도 간단합니다. claude를 실행한 뒤 /install-github-app을 치거나, GitHub 앱을 설치하고 ANTHROPIC_API_KEY를 시크릿으로 넣으면 됩니다. 용도는 버그 트리아지, 코드 리뷰, 신규 기능 구현이 대표적입니다.

한 가지 꼭 기억할 점은 보안 기본값입니다. 쓰기 권한이 있는 기여자만 트리거할 수 있고, 외부 기여자나 봇은 기본 차단됩니다. allowed_non_write_users: "*" 같은 설정은 이 제한을 통째로 푸는 중대한 보안 위험이라 공식 문서도 경고합니다.

발표 당시 "곧" → 현재 "정식": 무엇이 바뀌었나요

이 부분이 이 글에서 가장 중요합니다. 발표는 2025년 5월 22일이었고, 그때 "soon"이라던 것들이 지금은 대부분 정식 출시됐습니다.

왜 이름을 Claude Agent SDK로 바꿨을까요?

2025년 9월 29일, Anthropic은 Claude Sonnet 4.5, Claude Code 2.0과 함께 SDK 이름을 바꿨습니다. 이유는 명확합니다. Claude Code를 구동하는 에이전트 하네스(엔진)가 코딩 말고 다른 종류의 에이전트도 얼마든지 구동할 수 있다는 걸 확인했기 때문이죠. 그 넓어진 비전을 이름에 담은 겁니다.

이름만 바뀐 게 아닙니다. 서브에이전트(subagents), 라이프사이클 훅(hooks), Agent Skills 같은 기능이 함께 추가됐습니다.

마이그레이션은 생각보다 간단합니다

이미 구 패키지를 쓰고 있었다면 걱정 마세요. TypeScript는 @anthropic-ai/claude-code에서 @anthropic-ai/claude-agent-sdk로, Python은 claude-code-sdk에서 claude-agent-sdk(Python 3.10 이상)로 패키지만 바꾸면 됩니다. 코드에서는 옵션 타입 이름 하나(ClaudeCodeOptions → ClaudeAgentOptions) 정도만 바꾸면 되는 수준입니다.

참고로 Agent SDK와 Client SDK는 다릅니다. Client SDK는 API에 직접 접근하되 툴 실행을 직접 구현해야 하고, Agent SDK는 툴 실행, 에이전트 루프, 컨텍스트 관리가 안에 내장돼 Claude가 알아서 처리합니다. 에이전트를 만들 거라면 Agent SDK가 훨씬 편합니다.

마무리

정리하면 이렇습니다. Claude Code SDK(현 Claude Agent SDK)는 화면 없이 코드에서 부르는 헤드리스 AI 에이전트 도구이고, claude -p 파이프 한 줄이면 로그 요약부터 코드 자동화까지 시작할 수 있습니다. 그 위에 만들어진 @claude GitHub Actions는 이슈에 댓글 한 줄로 기능을 구현하는 팀 동료 같은 존재가 됐고요. 2025년 5월 발표에서 "곧"이라던 파이썬·타입스크립트 바인딩과 공식 GitHub Action은 이미 정식 출시된 상태입니다.

AI 코딩 자동화를 진지하게 고민하고 계신다면, 오늘 당장 ifconfig -a | claude -p "..." 한 줄부터 시작해 보세요. 손에 잡히는 감각이 확 달라집니다. 더 궁금한 점이 있으면 언제든 물어봐 주세요.

자주 묻는 질문 (FAQ)

Q: Claude Code SDK와 Claude Agent SDK는 다른 건가요?

같은 도구입니다. 2025년 9월 29일에 Claude Code SDK가 Claude Agent SDK로 이름을 바꾸며 범용 에이전트 하네스로 확장됐습니다. 기존 패키지를 쓰던 사람도 패키지 이름과 옵션 타입 하나만 바꾸면 그대로 넘어갈 수 있습니다.

Q: 헤드리스 모드는 어떻게 시작하나요?

claude -p "질문" 형태로 실행하면 대화창 없이 결과만 받습니다. 파이프로 로그나 명령어 출력을 넘길 수 있고, --output-format json을 붙이면 비용·세션 정보가 담긴 JSON으로 받아 다른 프로그램에서 활용할 수 있습니다.

Q: @claude GitHub Actions는 코드를 직접 고칠 수 있나요?

네. 정적 리뷰 도구와 달리 GitHub Actions 러너 안에서 Claude Code 런타임 전체가 돌기 때문에 파일 편집, 의존성 설치, 커밋 푸시까지 가능합니다. 다만 보안 기본값으로 쓰기 권한이 있는 기여자만 트리거할 수 있습니다.

참고 자료

• Claude Agent SDK 개요 (공식 문서)
• Building agents with the Claude Agent SDK (Anthropic 엔지니어링)
• 헤드리스 모드 문서
• claude-code-action (공식 GitHub)
• GitHub Actions 공식 가이드
• Agent SDK 마이그레이션 가이드
• Code with Claude 2025 (이벤트)