Class: HermesAgent::Client::Conversation

Inherits:
Object
  • Object
show all
Defined in:
lib/hermes_agent/client/conversation.rb

Overview

A stateful, multi-turn conversation over the Responses API that chains its turns automatically, so each call takes only the turn's input:.

Construct one via Resources::Responses#conversation rather than directly:

convo = client.responses.conversation
convo.create(input: "Hello").output_text
convo.create(input: "And what about X?").output_text  # auto-chains

There are two chaining mechanisms, selected at construction:

  • id-tracking mode (the default): the conversation remembers each turn's response id client-side and threads it into the next turn as previous_response_id. Pass previous_response_id: to resume such a thread from a known id (e.g. across process restarts).
  • named mode (name:): every turn sends a stable conversation name and the server keeps the thread; no client-side id is threaded.

The verb methods mirror Resources::Responses (#create / #stream_create) and return the same entities and stream, so the helper is a drop-in. #last_response_id is recorded in both modes for inspection or persistence.

A conversation models a single sequential thread and is not thread-safe: issue and (for streaming) consume one turn before starting the next.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#last_response_id ⇒ String? (readonly)

The id of the most recent turn's response (also the seed id before any turn, in id-tracking mode). In named mode it is recorded for inspection but not used for chaining.

Returns:

  • (String, nil) 


66
67
68
 
# File 'lib/hermes_agent/client/conversation.rb', line 66

def last_response_id
  @last_response_id
end

#name ⇒ String? (readonly)

The conversation name, in named mode; nil in id-tracking mode.

Returns:

  • (String, nil) 


58
59
60
 
# File 'lib/hermes_agent/client/conversation.rb', line 58

def name
  @name
end

Instance Method Details

#create(input:, **extra) ⇒ Entities::Response

Create the next turn in the conversation.

Parameters:

  • input (String, Array<Hash>) —

    The turn's input (see Resources::Responses#create).

  • extra (Hash) —

    Additional request-body fields merged into the body.

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



78
79
80
81
82
 
# File 'lib/hermes_agent/client/conversation.rb', line 78

def create(input:, **extra)
  response = @responses.create(input: input, **chaining, **extra)
  capture(response)
  response
end

#stream_create(input:, **extra) {|event| ... } ⇒ Entities::Response, Stream

Create the next turn, streaming its events. Follows the same block-or-enumerator contract as Resources::Responses#stream_create: with a block, each event is yielded and the assembled Entities::Response is returned; without one, a Stream is returned. In either case the turn's response id is captured into #last_response_id when the stream's result is built (during consumption), so a subsequent turn chains onto it.

Parameters:

  • input (String, Array<Hash>) —

    The turn's input.

  • extra (Hash) —

    Additional request-body fields merged into the body.

Yield Parameters:

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



100
101
102
103
104
 
# File 'lib/hermes_agent/client/conversation.rb', line 100

def stream_create(input:, **extra, &)
  @responses.stream_response(
    on_result: method(:capture), input: input, **chaining, **extra, &
  )
end