이번 주에 Python의 pip install claude-agent-sdk나 TypeScript의 npm install @anthropic-ai/claude-agent-sdk로 제공되는 Anthropic의 Claude Agent SDK의 Ruby 포팅 버전을 찾아보았습니다. 하지만 해당 목록에는 gem이 없었습니다. 즉, Ruby용 공식 Claude Agent SDK는 없으며, 변경 로그(changelog)상으로도 현재 개발 중인 것은 보이지 않습니다.

이는 처음 들었을 때 생각하는 것과는 다른 차원의 공백입니다. Ruby에는 이미 anthropics/anthropic-sdk-ruby에 있는 anthropic gem이라는 공식 Anthropic 라이브러리가 있지만, 그것은 Client SDK입니다. 즉, 도구 루프(tool loop)를 직접 작성해야 하는 단순 API 래퍼(wrapper)입니다. Agent SDK는 다른 제품입니다. Claude Code의 실제 하네스(harness)(에이전트 루프, 파일 시스템 도구, 권한, 훅, 서브 에이전트, MCP 지원)를 라이브러리로 패키징한 것입니다. Ruby에는 첫 번째는 있지만 두 번째는 없으며, 이를 검색하며 제가 목격한 대부분의 혼란은 이 둘을 동일한 것으로 취급하는 튜토리얼에서 비롯되었습니다. 명칭 문제도 일부 있습니다. Anthropic은 이것을 Claude Agent SDK로 이름을 바꾸기 전에 Claude Code SDK라고 불렀기 때문에, "claude code sdk ruby" 검색 결과도 동일한 공백에 빠지게 됩니다.

따라서 "SDK를 기다려야 하나요?"는 잘못된 질문이었습니다. 진짜 질문은 세 가지 경로 중 어떤 것이 Ruby에서 가장 마찰 없이 에이전트를 실행할 수 있느냐 하는 것입니다.

경로 1: 공식 gem을 사용한 수동 루프(hand-rolled loop)

이 방식은 에이전트가 파일 시스템이나 셸(shell)이 아닌, 내 앱 자체에서 동작해야 할 때 제가 선택하는 방식입니다. 송장을 조회하고 그에 대한 답장을 초안하는 것과 같은 작업 말입니다.

class Anthropic::AgentRunner
  def initialize(client: Anthropic::Client.new, tools:)
    @client = client
...

max_turns 제한이 있는 이유는 무한 루프에 빠질 수 있는 혼란스러운 에이전트가 계속해서 비용을 청구할 수 있기 때문입니다. 저는 에이전트가 백그라운드에서 동일한 도구 호출을 40번 재시도하는 것보다, 차라리 명확하게 에러를 발생시키는 것을 선호합니다.

루프 (loop)를 직접 제어하고 싶지 않다면, anthropic gem 또한 (현재는 beta.messages 네임스페이스 아래에 있는) tool_runner를 제공하며, 이는 모델이 요청을 멈출 때까지 모델 호출, 도구 실행, 결과 피드백을 반복하는 동일한 작업을 대신 수행해 줍니다. 저는 턴 (turn) 중간에 체크포인트가 필요한 경우(예: 이메일을 보내는 도구를 실행하기 전 인간의 승인 단계 등)에는 루프를 직접 작성하고, 그 외의 경우에는 tool_runner를 사용합니다.

경로 2: 비공식 claude-agent-sdk gem

만약 실제로 원하는 것이 Ruby에서 Claude Code 하네스 (harness) 자체를 사용하는 것이라면, 이를 위한 커뮤니티 gem이 있습니다: ya-luotao/claude-agent-sdk-ruby이며, claude-agent-sdk라는 이름으로 배포됩니다. 이 gem은 의도적으로 Python SDK의 형태를 모방합니다: 일회성 호출을 위한 ClaudeAgentSDK.query, 스트리밍 세션 (streaming sessions)을 위한 ClaudeAgentSDK::Client, 프로세스 내 도구 (in-process tools)를 위한 ClaudeAgentSDK.create_tool이 그 예입니다.

Gemfile에 추가하기 전에 알아두어야 할 기계적인 세부 사항이 하나 있습니다: 이 gem은 Anthropic API를 직접 호출하지 않습니다. 대신 claude CLI를 서브프로세스 (subprocess)로 호출하여 stdin/stdout을 통해 스트림 JSON (stream-JSON)으로 통신하며, 이는 공식 SDK들이 내부적으로 사용하는 것과 동일한 프로토콜입니다. 즉, 여러분의 Ruby 앱은 이제 CI를 포함하여 실행되는 모든 곳에서 Node.js와 CLI 의존성을 갖게 되며, gem들과 함께 @anthropic-ai/claude-code를 설치하게 됩니다.

또한 이 프로젝트는 아직 초기 단계입니다. 이 글을 쓰는 시점에 버전은 v0.19.0이며, 별(star)은 42개, 유지 관리자는 1명뿐이지만 이미 38번째 릴리스를 진행했습니다. 이러한 속도는 사이드 프로젝트로서 좋은 신호이지만, 만약 이 gem이 핵심적인 역할을 수행하게 된다면 정확한 버전을 고정(pin)해야 하는 이유이기도 합니다. README에는 Anthropic과 관련이 없다고 명시되어 있으며, 이를 있는 그대로 받아들이는 것이 좋습니다. 각 경로가 Bedrock 및 Vertex에 어떻게 도달하는지를 포함하여 세 가지 경로 모두를 더 심도 있게 비교한 내용은 제 사이트의 더 자세한 Claude Agent SDK in Ruby 비교 글에서 확인할 수 있습니다.

경로 3: Claude Code CLI로 쉘 아웃 (shell out)

가장 단순한 옵션이며, 때로는 CI 스크립트나 일회성 자동화에 적합한 방법입니다. 중간에 gem을 거치지 않고 claude -p "your prompt" --output-format json을 서브프로세스 (subprocess)로 실행한 뒤 반환되는 JSON을 파싱하는 방식입니다. (일반적인 claude -p는 텍스트를 출력하지만, 해당 플래그를 사용하면 출력을 파싱 가능한 형태로 만들어 줍니다.) 이는 커뮤니티 gem이 내부적으로 수행하고 있는 방식과 동일하며, 단지 그 위에 래핑된 Ruby 객체 모델(object model)이 없을 뿐입니다.

어떤 것을 선택해야 할까요

만약 에이전트 (agent)의 역할이 데이터베이스와 비즈니스 로직을 다루는 것이라면, 일반적인 anthropic gem을 사용하세요. 여러분이 실제로 원하는 하네스 (harness)는 다른 용도로 만들어진 범용 파일 시스템 및 쉘 하네스가 아니라, 기존의 권한 부여 (authorization) 기능이 갖춰진 여러분의 Rails 앱 자체입니다.

만약 에이전트의 역할이 파일과 쉘을 다루는 코딩 어시스턴트, 리팩토링 봇, 또는 CI 리뷰어라면, 그것이 바로 Claude Code 하네스가 만들어진 목적이며, 커뮤니티 gem이나 순수 CLI를 통해 그 목적을 달성할 수 있습니다. 저는 일반 API gem만을 사용하여 해당 하네스의 자체 버전을 만들지는 않을 것입니다. 그것은 이미 누군가가 구축하고 활발히 유지 관리하고 있는 방대한 인터페이스 (surface area)를 재발명하는 일이기 때문입니다.

더 넓은 범위에서 Rails로 에이전트를 구축하고 있다면, Claude 에이전트를 Rails 백그라운드 작업 (background jobs) 및 Turbo Streams에 연결하는 가이드도 참고해 보세요.