claude-agent-sdk-ruby（Claude Agent SDK Ruby 命令行）

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, runtime control APIs).
• 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.

1. Configure options:

- Set per-request options with ClaudeAgentSDK::ClaudeAgentOptions. - Set app-wide defaults with ClaudeAgentSDK.configure (especially in Rails initializers).

1. Handle messages:

- Parse assistant text from content blocks. - Stop on ClaudeAgentSDK::ResultMessage (final result, cost, session_id, structured output).

1. Handle runtime concerns:

- Rescue ClaudeAgentSDK::ControlRequestTimeoutError for long-running control requests. - Tune CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS when session orchestration needs longer waits.

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 (defaults, tools, permissions, output formats, budgets, sandbox, sessions, advanced flags).
• Read references/mcp-servers.md to define in-process SDK MCP tools/resources/prompts or configure external MCP servers.
• Read references/rails.md for initializers, background jobs, ActionCable streaming, and session resumption patterns.
• Read references/troubleshooting.md for common setup/runtime errors and timeout tuning.