Claude Agent SDK in Ruby: Your 3 Real Options

If you searched for "claude agent sdk ruby" hoping for a gem install, here is the short version: Anthropic does not ship one. That does not leave you stuck, though. There are three real ways to build a Claude agent in Ruby today, and picking the right one is mostly about how much of the Claude Code harness you actually need.

Is There an Official Claude Agent SDK for Ruby?

No. Anthropic ships the Claude Agent SDK for Python and TypeScript only; Ruby has no official port. The SDK (formerly called the Claude Code SDK) is Claude Code packaged as a library: the same agent loop, built-in tools, context management, hooks, subagents, and MCP support that power the CLI, exposed as pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk. There is no gem in that list, and the official changelog and bug tracker cover only the two languages.

This distinction matters, because a lot of tutorials blur the line between the Agent SDK and the plain API SDK. They are different products. The Anthropic Client SDK gives you direct API access where you implement the tool loop yourself; the Agent SDK gives you Claude with the tool loop, filesystem tools, and permissioning already built. Ruby has an official version of the first one (the anthropic gem) and no official version of the second.

So the real question for a Rubyist is not "wait for the SDK." It is "which of the three available paths gets you an agent with the least friction." Two of them are officially supported building blocks; one is a community gem that gets you closest to the Python and TypeScript developer experience.

The Unofficial Option: the claude-agent-sdk Gem

The claude-agent-sdk gem is an unofficial, community-maintained Ruby gem by ya-luotao that mirrors the Python Agent SDK's surface. It fills the gap Anthropic left, and it deserves a close look rather than a shrug. ya-luotao/claude-agent-sdk-ruby publishes as the claude-agent-sdk gem, and it deliberately mirrors the Python Agent SDK's surface: a ClaudeAgentSDK.query for single-turn calls, a ClaudeAgentSDK::Client for bidirectional streaming sessions with hooks and callbacks, ClaudeAgentSDK.create_tool for defining in-process tools, and a ClaudeAgentOptions configuration object. If you have used the Python SDK, the shapes will feel familiar.

The important mechanical detail: it does not call the Anthropic API directly. It wraps the claude CLI as a subprocess and communicates over stream-JSON on stdin and stdout, which is the same wire protocol the official SDKs use under the hood. The practical consequence is that the gem does not bundle a binary. You have to install the CLI separately (npm install -g @anthropic-ai/claude-code), which means your Ruby agent now has a Node.js and CLI dependency in every environment it runs in, including CI and production containers. It targets Ruby 3.2 and up.

Be honest with yourself about maturity. As of this writing the gem is at v0.19.0, sits at roughly 13,000 downloads and a few dozen GitHub stars, and moves fast (it is already on its 38th release). That is genuinely useful and clearly maintained, but it is a pre-1.0 project by one maintainer, not a supported Anthropic library. It is not affiliated with or supported by Anthropic, and the README says so. For a side project or an internal coding-automation tool, that trade is often fine. For something load-bearing in production, pin the exact version, read the changelog before every bump, and know that you own the risk if the underlying CLI protocol shifts.

Your Three Real Paths

The three real paths are the official anthropic gem with a hand-rolled agent loop, the unofficial claude-agent-sdk community gem, and shelling out to the claude CLI. The table runs top to bottom, from the simplest thing that works to the most capable.

The dividing question is what kind of agent you are building. If the agent acts on your database and business logic (look up an invoice, draft a reply, update a record), the plain anthropic gem is the right tool, because the "harness" you want is your own Rails app. If the agent acts on files, a repo, and the shell (a coding assistant, a refactor bot, a CI reviewer), the Claude Code harness is exactly what you want, and either the community gem or the CLI gives it to you.

How It Compares to Claude Code and to LangGraph

"Claude Agent SDK vs Claude Code" is close to a non-question: they are the same harness with different interfaces. Claude Code is the interactive CLI; the Agent SDK is that harness as a library. Anthropic's own guidance is to use the CLI for interactive development and one-off tasks, and the SDK for CI/CD and production automation.

"Claude Agent SDK vs LangGraph" is a different axis. LangGraph is a low-level, graph-based orchestration framework for stateful, long-running agents, built by the LangChain team. It is model-agnostic and centers on nodes, edges, and shared state with durable execution and human-in-the-loop checkpoints. But it is a Python framework (with a JS port), so for a Ruby shop it is not actually on the table unless you are willing to stand up a Python service. That is often the real reason Rubyists end up on one of the three paths above rather than a heavier orchestration framework.

Replicating the Agent Loop with the Official anthropic Gem

The official Anthropic Ruby SDK is the client (plain API) SDK, and the "agent" is a loop you run over it. For most Rails work, this is the path I reach for. The loop itself is small. You send the conversation, check whether the model asked for a tool, run it, feed the result back, and repeat until the model stops asking.

# Gemfile
gem "anthropic"

# config/initializers/anthropic.rb
# The client is threadsafe and pools connections, so create one and reuse it.
ANTHROPIC = Anthropic::Client.new(api_key: ENV.fetch("ANTHROPIC_API_KEY"))

The core loop, written by hand so you can see what the abstraction hides:

def run_agent(client:, tools:, messages:, model: "claude-sonnet-5", max_turns: 10)
  max_turns.times do
    response = client.messages.create(
      model: model,
      max_tokens: 1024,
      tools: tools.map(&:definition),
      messages: messages
    )

    # The model is done when it stops asking to use tools.
    break response if response.stop_reason != "tool_use"

    messages << { role: "assistant", content: response.content }

    # Execute every tool the model requested and return one result each.
    tool_results = response.content
      .select { |block| block.type == "tool_use" }
      .map { |block| execute_tool(tools, block) }

    messages << { role: "user", content: tool_results }
  end
end

That max_turns cap is not decoration. It is the cheapest guardrail against a confused agent that keeps calling tools and running up a bill. The official gem also ships a tool_runner (currently under the beta.messages namespace) that owns this exact loop for you, so in practice you hand-write the loop only when you need to intercept a tool call mid-turn, for example to gate an irreversible action behind human approval.

I have written the full version of this, including tool design, MCP, background jobs, human-in-the-loop, and testing, in building AI agents in Ruby with the Anthropic SDK. If you want a companion API reference for the gem itself, the Anthropic Ruby SDK guide covers the client, streaming, and error hierarchy in more depth. The short pitch: a mature Rails monolith already has the tools, the authorization, and the job infrastructure an agent needs, so the "agent" is a thin layer, not a rewrite.

Shelling Out to the Claude CLI

The claude CLI in non-interactive mode (claude -p), called from Ruby with Open3, lets you run a Claude agent with no gem at all. It is the honest answer when the job is "run Claude over this repo in CI" or "pipe a build log through Claude and write the explanation to a file." It is an official tool, it is the same harness as the SDK, and calling it from Ruby is just Open3.

require "open3"
require "json"

# claude -p runs non-interactively; --output-format json gives structured output.
stdout, status = Open3.capture2(
  "claude", "-p", "Summarize the staged diff and flag risky changes",
  "--output-format", "json",
  "--allowedTools", "Bash(git diff *),Read"
)

raise "claude failed" unless status.success?

payload = JSON.parse(stdout)
puts payload.fetch("result")
# payload also carries session metadata and, with json output, cost figures.

When this is the right call: CI linters and reviewers, scheduled maintenance scripts, and any glue where a subprocess boundary is acceptable and you would rather not carry a gem. The CLI supports --output-format json for a structured result with a session_id and cost data, --continue and --resume to thread conversations, and --bare to skip auto-discovery of hooks and MCP servers for reproducible runs.

When it is the wrong call: anything that wants a real object model, in-process custom tools, or tight streaming into a Rails UI. Parsing JSON out of a subprocess is fine for scripts and grating for an application. That is the line where the community gem or the plain anthropic gem earns its place.

When Each Path Falls Down

Every one of these has a failure mode, so pick with the downside in view.

The community gem carries a Node.js and CLI dependency into every environment, and it is pre-1.0 by a single maintainer. If the CLI's stream-JSON protocol changes upstream, you are waiting on a community fix. Pin the version, and do not put it on a critical path you cannot afford to babysit.

Shelling to the CLI means process spawn overhead per call, a subprocess to supervise, and stdout parsing that is brittle if you do not use --output-format json. It also inherits whatever .claude config and MCP servers exist in the working directory unless you pass --bare, which can make CI behave differently from a laptop.

The hand-rolled loop on the official gem gives you no filesystem harness at all: no built-in Read, Edit, Bash, Grep, or WebSearch tools. You build the tools you need. For agents over your own domain that is a feature, because you did not want the model running arbitrary shell commands anyway. For a coding agent it is a lot of reinvention, and you would be better served by the harness paths.

On Amazon Bedrock specifically ("claude agent sdk bedrock" is a common query): the official Agent SDK and CLI reach Bedrock through CLAUDE_CODE_USE_BEDROCK=1 and AWS credentials, and Vertex through CLAUDE_CODE_USE_VERTEX=1. The community Ruby gem inherits that because it shells to the same CLI. The official anthropic gem takes the other route with a dedicated Bedrock client for the plain API. Either way, Bedrock is reachable from Ruby; just know which layer is doing the talking.

Which Should You Choose?

Here is what I would actually reach for. If you are building an agent inside a Rails app that acts on your own data, use the official anthropic gem and run the loop (or its tool_runner). It is officially supported, it has no extra runtime dependencies, and it reuses the authorization and job infrastructure you already have. This is the default, and it is where most production Rails agents belong.

If you want the Claude Code experience in Ruby (an agent that reads files, runs commands, and edits code) and you are comfortable owning a pre-1.0 dependency, try the community claude-agent-sdk gem. It is the closest thing to the Python and TypeScript developer experience, and for coding automation it saves you from rebuilding the harness. Just pin the version and keep the Node.js dependency in mind.

If the task is a script or a CI step and you do not want a gem in the loop at all, shell out to the claude CLI with --output-format json. It is official, it is stable, and it is honest about what it is: a subprocess, not an object model.

The one path I would not take is waiting. There is no announced official Ruby Agent SDK, and you can build a solid agent today on any of the three.

What's Next?

The natural follow-on is tool design and the production concerns (background jobs, human approval, prompt-injection defenses, testing) that separate a demo from something you can ship. Those apply no matter which of the three paths you pick, because they live in your code, not the SDK.

Need help building a Claude agent on top of your Rails application? I work with teams on agent architecture, tool design, and the authorization and observability patterns that make an agent safe to ship. Reach out at hello at nsinenko.com.

Further Reading

• Building AI Agents in Ruby with the Anthropic SDK - the full agent loop, tools, MCP, background jobs, and testing on the official gem
• Anthropic Ruby SDK: A Practical Guide - the client, streaming, tool runner, and error handling for the official gem
• Rails AI Agents - the hub for agent patterns, tool calling, cost control, and guardrails in Rails
• Claude Agent SDK overview - Anthropic's official docs (Python and TypeScript)
• ya-luotao/claude-agent-sdk-ruby - the unofficial community gem
• anthropic-sdk-ruby on GitHub - the official Ruby API SDK

</content> </invoke>