Claude Agent SDK for Ruby

Quick start

• •Use ClaudeAgentSDK.query for one-shot prompts (unidirectional streaming).
• •Use ClaudeAgentSDK::Client for interactive sessions (multiple turns, interrupt, hooks, permission callbacks, custom tools).
• •Install prerequisites: Ruby 3.2+, Node.js, and Claude Code CLI.

require 'claude_agent_sdk'

ClaudeAgentSDK.query(prompt: "What is 2 + 2?") do |message|
  puts message.inspect
end

Workflow

1. •Choose an interface:
   • •Use ClaudeAgentSDK.query for simple, stateless calls.
   • •Use ClaudeAgentSDK::Client when you need bidirectional control (send multiple prompts, interrupt, change model/permissions, rewind files) or when using hooks/permission callbacks/custom tools.
2. •Configure ClaudeAgentSDK::ClaudeAgentOptions (only what you need).
3. •Handle messages:
   • •Parse assistant text from content blocks.
   • •Stop on ClaudeAgentSDK::ResultMessage (final result, cost, session_id, structured output).

Use these references

• •Read references/message-handling.md to extract text/tool blocks, capture UserMessage#uuid for rewind, and use ResultMessage fields.
• •Read references/options.md to configure ClaudeAgentOptions (tools, permissions, output formats, budgets, sandbox, sessions).
• •Read references/mcp-servers.md to define in-process SDK MCP tools/resources/prompts or configure external MCP servers.
• •Read references/rails.md for background jobs, ActionCable streaming, and session resumption patterns.
• •Read references/troubleshooting.md for common setup and runtime errors.