Back to Details

claude-agent-sdk-ruby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Agent SDK for Ruby

Ruby版Claude Agent SDK

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.

ruby

require 'claude_agent_sdk'

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

使用
```
ClaudeAgentSDK.query
```
处理一次性提示词（单向流式传输）。
使用
```
ClaudeAgentSDK::Client
```
进行交互式会话（多轮对话、中断、钩子、权限回调、自定义工具）。
安装前提条件：Ruby 3.2+、Node.js和Claude Code CLI。

ruby

require 'claude_agent_sdk'

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

Workflow

工作流程

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.
Configure
```
ClaudeAgentSDK::ClaudeAgentOptions
```
(only what you need).
Handle messages:
- Parse assistant text from content blocks.
- Stop on
```
ClaudeAgentSDK::ResultMessage
```
  (final result, cost, session_id, structured output).

选择接口：
- 若只需简单的无状态调用，使用
```
ClaudeAgentSDK.query
```
  。
- 当需要双向控制（发送多个提示词、中断、更改模型/权限、回退文件）或使用钩子/权限回调/自定义工具时，使用
```
ClaudeAgentSDK::Client
```
  。
配置
```
ClaudeAgentSDK::ClaudeAgentOptions
```
（按需配置即可）。
处理消息：
- 从内容块中解析助手文本。
- 遇到
```
ClaudeAgentSDK::ResultMessage
```
  时停止（包含最终结果、成本、session_id、结构化输出）。

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.

阅读
```
references/message-handling.md
```
以提取文本/工具块、捕获
```
UserMessage#uuid
```
用于回退，以及使用
```
ResultMessage
```
字段。
阅读
```
references/options.md
```
以配置
```
ClaudeAgentOptions
```
（工具、权限、输出格式、预算、沙箱、会话）。
阅读
```
references/mcp-servers.md
```
以定义进程内SDK MCP工具/资源/提示词，或配置外部MCP服务器。
阅读
```
references/rails.md
```
了解后台任务、ActionCable流式传输和会话恢复模式。
阅读
```
references/troubleshooting.md
```
排查常见的设置和运行时错误。