Module: ClaudeAgentSDK::Observer

Included in:
Instrumentation::OTelObserver
Defined in:
lib/claude_agent_sdk/observer.rb

Overview

Base module for message observers.

Include this module and override the methods you care about. All methods have no-op defaults so observers only need to implement the callbacks relevant to their use case.

Observers are registered via ClaudeAgentOptions#observers and are called for every parsed message in both query() and Client#receive_messages. Observer errors are rescued so they never crash the main message pipeline.

Examples:

Custom logging observer

class LoggingObserver
  include ClaudeAgentSDK::Observer

  def on_message(message)
    puts "[#{message.class.name}] received"
  end
end

Instance Method Summary collapse

Instance Method Details

#on_close ⇒ Object

Called when the query or client disconnects. Use this to flush buffers. In Client mode call disconnect (ideally in an ensure block) so on_close runs and instrumentation (e.g. OTel spans) is flushed/exported.



56
 
# File 'lib/claude_agent_sdk/observer.rb', line 56

def on_close; end

#on_error(error) ⇒ Object

Called once per error that surfaces from query() or from Client#query/#receive_messages/#receive_response/#connect (after argument/configuration validation — usage errors such as ‘Not connected’ or invalid options do not notify) — including errors raised by the user’s own message block — before on_close where both fire. query() fires on_close even for connect-phase failures (its ensure always runs); a Client#connect failure before the handshake completes fires on_error WITHOUT on_close (the session never opened). Not notified (by design): errors raised by control-request methods (interrupt, set_model, …) — the same error also reaches the message stream where it is notified once; errors during query()‘s own teardown; and input-stream errors swallowed by streaming input (warn only, matching the Python SDK).

Parameters:

  • error (StandardError) —

    The error that occurred



51
 
# File 'lib/claude_agent_sdk/observer.rb', line 51

def on_error(error); end

#on_message(message) ⇒ Object

Called for every parsed message (typed object from MessageParser).

Parameters:

  • message (Object) —

    A typed message (AssistantMessage, ResultMessage, etc.)



36
 
# File 'lib/claude_agent_sdk/observer.rb', line 36

def on_message(message); end

#on_user_prompt(prompt) ⇒ Object

Called with the user’s prompt text (not echoed back by CLI in streaming mode): the verbatim string for String prompts (query() / Client#query), and once per ‘type: ’user’‘ message for Enumerator/streaming input with extracted text (string content, or newline-joined non-empty top-level text blocks). User messages with no extractable text (tool_result-only, image-only, empty text) are skipped; only Hash or JSON-string stream items are inspected. In streaming mode, ordering relative to on_message is not guaranteed.

Parameters:

  • prompt (String) —

    The user’s prompt string



32
 
# File 'lib/claude_agent_sdk/observer.rb', line 32

def on_user_prompt(prompt); end