Class: HermesAgent::Client::Resources::Responses

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

Overview

The responses resource: the Responses API (/v1/responses). Unlike chat completions, the server persists conversation state, so turns can be chained (via previous_response_id or a named conversation) and a response can be retrieved or deleted by id afterward. On a server configured with an API key, these calls require a bearer token (see HermesAgent::Client / Configuration).

Server-side storage is capped (LRU eviction), so callers should not assume an older response remains retrievable.

Instance Method Summary collapse

Instance Method Details

#conversation(name: nil, previous_response_id: nil) ⇒ Conversation

Begin a multi-turn conversation that automatically chains its turns.

Returns a Conversation — a stateful helper wrapping this resource — whose create / stream_create take only the per-turn input: (plus extra) and handle chaining for you. With no arguments it tracks the previous_response_id of each turn client-side and threads it into the next; pass name: instead to chain via a server-side named conversation; pass previous_response_id: to resume a client-side thread from a known id. name: and previous_response_id: are mutually exclusive (they select different chaining mechanisms).

Parameters:

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

    A stable conversation name for server-side chaining. Mutually exclusive with previous_response_id.

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

    A prior response id to seed client-side chaining from. Mutually exclusive with name.

Returns:



157
158
159
 
# File 'lib/hermes_agent/client/resources/responses.rb', line 157

def conversation(name: nil, previous_response_id: nil)
  Conversation.new(self, name: name, previous_response_id: previous_response_id)
end

#create(input:, previous_response_id: nil, conversation: nil, idempotency_key: nil, **extra) ⇒ Entities::Response

Create a response.

No model is sent: the model is configured server-side and the server ignores a client-supplied one. (A caller who really wants to send fields we have not modeled — including model — can pass them through extra.)

Parameters:

  • input (String, Array<Hash>) —

    The input: a plain string, or an array of input items (which may include input_image parts for inline images).

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

    The id of a prior response to chain this turn onto. Omitted from the request when nil.

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

    A stable conversation name to chain this turn onto. Omitted from the request when nil.

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

    An idempotency key, sent as the Idempotency-Key request header. The server caches the result for ~5 minutes and replays it for a repeat call carrying the same key and an equivalent request, so a retry does not re-run the model. The replay is transparent: the response is indistinguishable from a fresh one (same status, no replay header, and a freshly regenerated id), so there is no way — here or in the returned entity — to tell whether a given call was served from the cache. Reusing a key with a different request silently recomputes (no error) and overwrites the cached entry. Honored only on this non-streaming endpoint (not on #stream_create).

  • extra (Hash) —

    Additional request-body fields merged into the body as-is.

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



66
67
68
69
70
71
 
# File 'lib/hermes_agent/client/resources/responses.rb', line 66

def create(input:, previous_response_id: nil, conversation: nil, idempotency_key: nil, **extra)
  body = build_body(input, previous_response_id, conversation, extra)
  headers = idempotency_key ? {"Idempotency-Key" => idempotency_key} : nil
  result = @transport.post("/v1/responses", body, headers: headers)
  Entities::Response.new(result.body, **Util.session_headers(result.headers))
end

#delete(id) ⇒ Entities::ResponseDeletion

Delete a response by id.

Parameters:

  • id (String) —

    The response id ("resp_…").

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



180
181
182
 
# File 'lib/hermes_agent/client/resources/responses.rb', line 180

def delete(id)
  Entities::ResponseDeletion.new(@transport.delete("/v1/responses/#{id}"))
end

#get(id) ⇒ Entities::Response

Retrieve a previously created response by id.

Parameters:

  • id (String) —

    The response id ("resp_…").

Returns:

Raises:

  • (NotFoundError) —

    If no such response exists (or it was evicted).

  • (APIError) —

    If the server returns another non-2xx response.



169
170
171
 
# File 'lib/hermes_agent/client/resources/responses.rb', line 169

def get(id)
  Entities::Response.new(@transport.get("/v1/responses/#{id}"))
end

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

Create a response, streaming the turn's events.

With a block, each Entities::ResponseStreamEvent is yielded as it arrives and the assembled Entities::Response is returned once the stream closes. Without a block, a Stream is returned for the caller to iterate; its Stream#result is the assembled response. The final response is taken from the terminal response.completed event (see Entities::Response.from_events).

Parameters:

  • input (String, Array<Hash>) —

    The input (see #create).

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

    The id of a prior response to chain onto. Omitted from the request when nil.

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

    A stable conversation name to chain onto. Omitted from the request when nil.

  • extra (Hash) —

    Additional request-body fields merged into the body as-is.

Yield Parameters:

Returns:

Raises:

  • (APIError) —

    If the server returns a non-2xx response.



95
96
97
98
 
# File 'lib/hermes_agent/client/resources/responses.rb', line 95

def stream_create(input:, previous_response_id: nil, conversation: nil, **extra, &)
  stream_response(on_result: nil, input: input, previous_response_id: previous_response_id,
                  conversation: conversation, **extra, &)
end