Class: HermesAgent::Client::Entities::Response

Inherits:
HermesAgent::Client::Entity show all
Includes:
SessionHeaders
Defined in:
lib/hermes_agent/client/entities/response.rb

Overview

A response from the Responses API (POST /v1/responses, GET /v1/responses/{id}). The server persists conversation state, so a response can be retrieved later and chained from. Field readers are best-effort; HermesAgent::Client::Entity#to_h remains the source of truth.

Instance Attribute Summary

Attributes included from SessionHeaders

#session_id, #session_key

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SessionHeaders

#==, #hash

Methods inherited from HermesAgent::Client::Entity

#==, #[], #eql?, #hash, #to_h

Class Method Details

.from_events(events, session_id: nil, session_key: nil) ⇒ Response

Build a HermesAgent::Client::Entities::Response from a streamed turn's events. The terminal response.completed event carries the full final response object, so this takes the last response payload seen across the events (which is that terminal one — response.created carries an interim one). Returns a HermesAgent::Client::Entities::Response wrapping an empty payload if no event carried a response object.

Parameters:

  • events (Array<ResponseStreamEvent>) —

    The streamed events, in order.

  • session_id (String, nil) (defaults to: nil) —

    The session id from the response headers, carried onto the assembled response.

  • session_key (String, nil) (defaults to: nil) —

    The session key from the response headers, carried onto the assembled response.

Returns:



218
219
220
221
222
223
224
225
 
# File 'lib/hermes_agent/client/entities/response.rb', line 218

def self.from_events(events, session_id: nil, session_key: nil)
  payload = {}
  events.each do |event|
    raw = event["response"]
    payload = raw if raw.is_a?(::Hash)
  end
  new(payload, session_id: session_id, session_key: session_key)
end

Instance Method Details

#created_at ⇒ Integer?

When the response was created, as a Unix timestamp (seconds).

Returns:

  • (Integer, nil) 


256
257
258
 
# File 'lib/hermes_agent/client/entities/response.rb', line 256

def created_at
  self["created_at"]
end

#id ⇒ String?

The response id, e.g. "resp_…". Pass it as previous_response_id to chain a follow-up turn.

Returns:

  • (String, nil) 


232
233
234
 
# File 'lib/hermes_agent/client/entities/response.rb', line 232

def id
  self["id"]
end

#model ⇒ String?

The model that produced the response, e.g. "hermes-test".

Returns:

  • (String, nil) 


264
265
266
 
# File 'lib/hermes_agent/client/entities/response.rb', line 264

def model
  self["model"]
end

#object ⇒ String?

The object type, "response".

Returns:

  • (String, nil) 


240
241
242
 
# File 'lib/hermes_agent/client/entities/response.rb', line 240

def object
  self["object"]
end

#output ⇒ Array<ResponseOutputItem>?

The output items, each wrapped in a HermesAgent::Client::Entities::ResponseOutputItem. Returns nil when the field is absent.

Returns:



273
274
275
276
277
278
 
# File 'lib/hermes_agent/client/entities/response.rb', line 273

def output
  raw = self["output"]
  return nil unless raw.is_a?(::Array)

  raw.map { |item| ResponseOutputItem.new(item) }
end

#output_text ⇒ String?

The assistant's text: the concatenation of the text of every message output item, ignoring tool items. A convenience over #output for the common single-message case. Returns nil when there is no output.

Returns:

  • (String, nil) 


297
298
299
300
301
302
 
# File 'lib/hermes_agent/client/entities/response.rb', line 297

def output_text
  items = output
  return nil unless items

  items.select { |item| item.type == "message" }.filter_map(&:text).join
end

#status ⇒ String?

The response status, e.g. "completed" or "in_progress".

Returns:

  • (String, nil) 


248
249
250
 
# File 'lib/hermes_agent/client/entities/response.rb', line 248

def status
  self["status"]
end

#usage ⇒ ResponseUsage?

The token usage, wrapped in a HermesAgent::Client::Entities::ResponseUsage. Returns nil when the field is absent.

Returns:



285
286
287
288
 
# File 'lib/hermes_agent/client/entities/response.rb', line 285

def usage
  raw = self["usage"]
  raw.is_a?(::Hash) ? ResponseUsage.new(raw) : nil
end