claude-agent-ruby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Agent Ruby SDK

Overview

概述

Use this skill to build or refactor Ruby integrations with Claude Code via

claude-agent-sdk

, favoring the gem's README and types for exact APIs.

使用此技能通过

claude-agent-sdk

构建或重构与Claude Code的Ruby集成，优先参考gem的README和类型定义以获取准确的API信息。

Decision Guide

决策指南

Choose
```
ClaudeAgentSDK.query
```
for one-shot queries or streaming input. Internally uses the control protocol (streaming mode) since v0.7.0.
Choose
```
ClaudeAgentSDK::Client
```
for multi-turn sessions, hooks, permission callbacks, or dynamic model switching; wrap in
```
Async do ... end.wait
```
.
Choose SDK MCP servers (
```
create_tool
```
,
```
create_sdk_mcp_server
```
) for in-process tools; choose external MCP configs for subprocess/HTTP servers.

对于一次性查询或流式输入，选择
```
ClaudeAgentSDK.query
```
。自v0.7.0版本起，其内部使用控制协议（流式模式）。
对于多轮会话、钩子、权限回调或动态模型切换，选择
```
ClaudeAgentSDK::Client
```
；需将其包裹在
```
Async do ... end.wait
```
中执行。
对于进程内工具，选择SDK MCP服务器（
```
create_tool
```
、
```
create_sdk_mcp_server
```
）；对于子进程/HTTP服务器，选择外部MCP配置。

Implementation Checklist

实施检查清单

Confirm prerequisites (Ruby 3.2+, Node.js, Claude Code CLI).

Build

ClaudeAgentSDK::ClaudeAgentOptions

and pass it to

query

Client.new

Handle messages by type (
```
AssistantMessage
```
,
```
ResultMessage
```
,
```
UserMessage
```
, etc.) and content blocks (
```
TextBlock
```
,
```
ToolUseBlock
```
, etc.).
Use
```
output_format
```
and read
```
StructuredOutput
```
tool-use blocks for JSON schema responses.

Use

thinking:

with

ThinkingConfigAdaptive

ThinkingConfigEnabled(budget_tokens:)

, or

ThinkingConfigDisabled

to control extended thinking. Use

effort:

(

'low'

'medium'

'high'

) for effort level.

Define hooks and permission callbacks as Ruby procs/lambdas; do not combine
```
can_use_tool
```
with
```
permission_prompt_tool_name
```
. Hook inputs include
```
tool_use_id
```
on
```
PreToolUseHookInput
```
and
```
PostToolUseHookInput
```
.
For SDK MCP tools, include
```
mcp__<server>__<tool>
```
in
```
allowed_tools
```
. Use
```
annotations:
```
on
```
create_tool
```
for MCP tool annotations.
Use
```
tools
```
or
```
ToolsPreset
```
for base tool selection; use
```
append_allowed_tools
```
when extending defaults.
Configure sandboxing via
```
SandboxSettings
```
and
```
SandboxNetworkConfig
```
when requested.
Use
```
resume
```
,
```
session_id
```
, and
```
fork_session
```
for session handling; enable file checkpointing only when explicitly needed.
Note: when
```
system_prompt
```
is nil (default), the SDK passes
```
--system-prompt ""
```
to suppress the default Claude Code system prompt.

确认前置条件（Ruby 3.2+、Node.js、Claude Code CLI）。

构建

ClaudeAgentSDK::ClaudeAgentOptions

并将其传入

query

或

Client.new

。

按类型处理消息（
```
AssistantMessage
```
、
```
ResultMessage
```
、
```
UserMessage
```
等）和内容块（
```
TextBlock
```
、
```
ToolUseBlock
```
等）。
使用
```
output_format
```
并读取
```
StructuredOutput
```
工具使用块以获取JSON Schema响应。

使用

thinking:

参数搭配

ThinkingConfigAdaptive

、

ThinkingConfigEnabled(budget_tokens:)

或

ThinkingConfigDisabled

来控制扩展思考功能。使用

effort:

参数（

'low'

、

'medium'

、

'high'

）设置努力级别。

将钩子和权限回调定义为Ruby proc/λ表达式；不要将
```
can_use_tool
```
与
```
permission_prompt_tool_name
```
结合使用。钩子输入在
```
PreToolUseHookInput
```
和
```
PostToolUseHookInput
```
中包含
```
tool_use_id
```
。
对于SDK MCP工具，需在
```
allowed_tools
```
中包含
```
mcp__<server>__<tool>
```
。在
```
create_tool
```
上使用
```
annotations:
```
参数添加MCP工具注解。
使用
```
tools
```
或
```
ToolsPreset
```
选择基础工具；扩展默认工具时使用
```
append_allowed_tools
```
。
当需要时，通过
```
SandboxSettings
```
和
```
SandboxNetworkConfig
```
配置沙箱。
使用
```
resume
```
、
```
session_id
```
和
```
fork_session
```
处理会话；仅在明确需要时启用文件检查点。
注意：当
```
system_prompt
```
为nil（默认值）时，SDK会传递
```
--system-prompt ""
```
以禁用默认的Claude Code系统提示。

Where To Look For Exact Details

详细信息查询位置

Locate the gem path with

bundle show claude-agent-sdk

ruby -e 'puts Gem::Specification.find_by_name(\"claude-agent-sdk\").full_gem_path'

Read
```
<gem_path>/README.md
```
for canonical usage and option examples.
Inspect
```
<gem_path>/lib/claude_agent_sdk/types.rb
```
for the full options and type list.

Inspect

<gem_path>/lib/claude_agent_sdk/errors.rb

for error classes and handling.

Use
```
references/usage-map.md
```
for a README section map and minimal skeletons.

使用

bundle show claude-agent-sdk

或

ruby -e 'puts Gem::Specification.find_by_name("claude-agent-sdk").full_gem_path'

查找gem的路径。

阅读
```
<gem_path>/README.md
```
获取标准用法和选项示例。
查看
```
<gem_path>/lib/claude_agent_sdk/types.rb
```
获取完整的选项和类型列表。

查看

<gem_path>/lib/claude_agent_sdk/errors.rb

获取错误类和处理方式。

使用
```
references/usage-map.md
```
获取README章节映射和最小化代码骨架。

Resources

资源

references/

Use

references/usage-map.md

to map tasks to README sections and gem paths.

使用

references/usage-map.md

将任务映射到README章节和gem路径。",