Module: ClaudeAgentSDK

Defined in:
lib/claude_agent_sdk.rb,
lib/claude_agent_sdk/query.rb,
lib/claude_agent_sdk/types.rb,
lib/claude_agent_sdk/errors.rb,
lib/claude_agent_sdk/version.rb,
lib/claude_agent_sdk/transport.rb,
lib/claude_agent_sdk/message_parser.rb,
lib/claude_agent_sdk/sdk_mcp_server.rb,
lib/claude_agent_sdk/subprocess_cli_transport.rb

Overview

Claude Agent SDK for Ruby

Defined Under Namespace

Classes: AgentDefinition, AssistantMessage, CLIConnectionError, CLIJSONDecodeError, CLINotFoundError, ClaudeAgentOptions, ClaudeSDKError, Client, HookMatcher, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, McpStdioServerConfig, MessageParseError, MessageParser, PermissionResultAllow, PermissionResultDeny, PermissionRuleValue, PermissionUpdate, ProcessError, Query, ResultMessage, SdkMcpServer, SdkMcpTool, StreamEvent, SubprocessCLITransport, SystemMessage, TextBlock, ThinkingBlock, ToolPermissionContext, ToolResultBlock, ToolUseBlock, Transport, UserMessage

Constant Summary collapse

VERSION = 
'0.1.1'

Class Method Summary collapse

Class Method Details

.create_sdk_mcp_server(name:, version: '1.0.0', tools: []) ⇒ Hash

Create an SDK MCP server

Examples:

Simple calculator server

add_tool = ClaudeAgentSDK.create_tool('add', 'Add numbers', { a: :number, b: :number }) do |args|
  { content: [{ type: 'text', text: "Sum: #{args[:a] + args[:b]}" }] }
end

calculator = ClaudeAgentSDK.create_sdk_mcp_server(
  name: 'calculator',
  version: '2.0.0',
  tools: [add_tool]
)

options = ClaudeAgentOptions.new(
  mcp_servers: { calc: calculator },
  allowed_tools: ['mcp__calc__add']
)

Parameters:

  • name (String) —

    Unique identifier for the server

  • version (String) (defaults to: '1.0.0') —

    Server version (default: ‘1.0.0’)

  • tools (Array<SdkMcpTool>) (defaults to: []) —

    List of tool definitions

Returns:

  • (Hash) —

    MCP server configuration for ClaudeAgentOptions



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/claude_agent_sdk/sdk_mcp_server.rb', line 155

def self.create_sdk_mcp_server(name:, version: '1.0.0', tools: [])
  server = SdkMcpServer.new(name: name, version: version, tools: tools)

  # Return configuration for ClaudeAgentOptions
  {
    type: 'sdk',
    name: name,
    instance: server
  }
end

.create_tool(name, description, input_schema, &handler) ⇒ SdkMcpTool

Helper function to create a tool definition

Examples:

Simple tool

tool = create_tool('greet', 'Greet a user', { name: :string }) do |args|
  { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
end

Tool with multiple parameters

tool = create_tool('add', 'Add two numbers', { a: :number, b: :number }) do |args|
  result = args[:a] + args[:b]
  { content: [{ type: 'text', text: "Result: #{result}" }] }
end

Tool with error handling

tool = create_tool('divide', 'Divide numbers', { a: :number, b: :number }) do |args|
  if args[:b] == 0
    { content: [{ type: 'text', text: 'Error: Division by zero' }], is_error: true }
  else
    result = args[:a] / args[:b]
    { content: [{ type: 'text', text: "Result: #{result}" }] }
  end
end

Parameters:

  • name (String) —

    Unique identifier for the tool

  • description (String) —

    Human-readable description

  • input_schema (Hash) —

    Schema defining input parameters

  • handler (Proc) —

    Block that implements the tool logic

Returns:

Raises:

  • (ArgumentError) 


122
123
124
125
126
127
128
129
130
131
 
# File 'lib/claude_agent_sdk/sdk_mcp_server.rb', line 122

def self.create_tool(name, description, input_schema, &handler)
  raise ArgumentError, 'Block required for tool handler' unless handler

  SdkMcpTool.new(
    name: name,
    description: description,
    input_schema: input_schema,
    handler: handler
  )
end

.query(prompt:, options: nil) {|Message| ... } ⇒ Enumerator

Query Claude Code for one-shot or unidirectional streaming interactions

This function is ideal for simple, stateless queries where you don’t need bidirectional communication or conversation management.

Examples:

Simple query

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

With options

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  allowed_tools: ['Read', 'Bash'],
  permission_mode: 'acceptEdits'
)
ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |msg|
  if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
    msg.content.each do |block|
      puts block.text if block.is_a?(ClaudeAgentSDK::TextBlock)
    end
  end
end

Parameters:

  • prompt (String) —

    The prompt to send to Claude

  • options (ClaudeAgentOptions) (defaults to: nil) —

    Optional configuration

Yields:

  • (Message) —

    Each message from the conversation

Returns:

  • (Enumerator) —

    if no block given



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/claude_agent_sdk.rb', line 43

def self.query(prompt:, options: nil, &block)
  return enum_for(:query, prompt: prompt, options: options) unless block

  options ||= ClaudeAgentOptions.new
  ENV['CLAUDE_CODE_ENTRYPOINT'] = 'sdk-rb'

  Async do
    transport = SubprocessCLITransport.new(prompt, options)
    begin
      transport.connect
      transport.read_messages do |data|
        message = MessageParser.parse(data)
        block.call(message)
      end
    ensure
      transport.close
    end
  end.wait
end