Class: Cerca::Resources::Threads

Inherits:
Object
  • Object
show all
Defined in:
lib/cerca/resources/threads.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Threads

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Threads.

Parameters:



228
229
230
 
# File 'lib/cerca/resources/threads.rb', line 228

def initialize(client:)
  @client = client
end

Instance Method Details

#cancel(agent_id, thread_id, request_options: {}) ⇒ Cerca::Models::Thread

Cancel a running or awaiting thread. The underlying runtime treats repeat cancellation as an idempotent lifecycle operation when possible.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



117
118
119
120
121
122
123
124
 
# File 'lib/cerca/resources/threads.rb', line 117

def cancel(agent_id, thread_id, params = {})
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads/%2$s/cancel", agent_id, thread_id],
    model: Cerca::Thread,
    options: params[:request_options]
  )
end

#close(agent_id, thread_id, request_options: {}) ⇒ Cerca::Models::Thread

Close an idle thread. Closing a running, awaiting, or already-closed thread returns a lifecycle conflict.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



138
139
140
141
142
143
144
145
 
# File 'lib/cerca/resources/threads.rb', line 138

def close(agent_id, thread_id, params = {})
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads/%2$s/close", agent_id, thread_id],
    model: Cerca::Thread,
    options: params[:request_options]
  )
end

#compact(agent_id, thread_id, request_options: {}) ⇒ Cerca::Models::Thread

Force context compaction for an idle thread. Compacting a running thread returns a lifecycle conflict.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



159
160
161
162
163
164
165
166
 
# File 'lib/cerca/resources/threads.rb', line 159

def compact(agent_id, thread_id, params = {})
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads/%2$s/compact", agent_id, thread_id],
    model: Cerca::Thread,
    options: params[:request_options]
  )
end

#create(agent_id, instructions: nil, message: nil, model: nil, system_prompt: nil, tools: nil, request_options: {}) ⇒ Cerca::Models::Thread

Some parameter documentations has been truncated, see Models::ThreadCreateParams for more details.

Create thread

Parameters:

  • agent_id (String)
  • instructions (String)
  • message (String)
  • model (String)
  • system_prompt (String) —

    Deprecated alias for ‘instructions`; accepted for backwards compatibility.

  • tools (Array<String>) —

    Per-thread tool subset. Omit to inherit the agent’s full effective tools; pass [

  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/cerca/resources/threads.rb', line 30

def create(agent_id, params = {})
  parsed, options = Cerca::ThreadCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads", agent_id],
    body: parsed,
    model: Cerca::Thread,
    options: options
  )
end

#list(agent_id, cursor: nil, limit: nil, schedule_id: nil, status: nil, request_options: {}) ⇒ Cerca::Internal::ThreadsCursorPage<Cerca::Models::ThreadSummary>

Some parameter documentations has been truncated, see Models::ThreadListParams for more details.

List threads

Parameters:

  • agent_id (String)
  • cursor (String) —

    Opaque pagination cursor returned by a previous request.

  • limit (String) —

    Maximum number of items to return. Defaults to 20 and preserves parseInt semanti

  • schedule_id (String) —

    Optional schedule id filter.

  • status (Symbol, Cerca::Models::Status) —

    Optional thread status filter.

  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/cerca/resources/threads.rb', line 92

def list(agent_id, params = {})
  parsed, options = Cerca::ThreadListParams.dump_request(params)
  query = Cerca::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["agents/%1$s/threads", agent_id],
    query: query.transform_keys(schedule_id: "scheduleId"),
    page: Cerca::Internal::ThreadsCursorPage,
    model: Cerca::ThreadSummary,
    options: options
  )
end

#retrieve(agent_id, thread_id, debug: nil, include_messages: nil, request_options: {}) ⇒ Cerca::Models::Thread

Retrieve thread

Parameters:

Returns:

See Also:



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/cerca/resources/threads.rb', line 58

def retrieve(agent_id, thread_id, params = {})
  parsed, options = Cerca::ThreadRetrieveParams.dump_request(params)
  query = Cerca::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["agents/%1$s/threads/%2$s", agent_id, thread_id],
    query: query.transform_keys(include_messages: "includeMessages"),
    model: Cerca::Thread,
    options: options
  )
end

#start_turn(agent_id, thread_id, message:, model: nil, tools: nil, request_options: {}) ⇒ Cerca::Models::Turn

Some parameter documentations has been truncated, see Models::ThreadStartTurnParams for more details.

Create turn

Parameters:

  • agent_id (String)
  • thread_id (String)
  • message (String)
  • model (String)
  • tools (Array<String>) —

    Per-turn tool subset. Omit to inherit the thread’s current tools; pass [] to run

  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/cerca/resources/threads.rb', line 190

def start_turn(agent_id, thread_id, params)
  parsed, options = Cerca::ThreadStartTurnParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads/%2$s/turns", agent_id, thread_id],
    body: parsed,
    model: Cerca::Turn,
    options: options
  )
end

#steer(agent_id, thread_id, message:, request_options: {}) ⇒ Cerca::Models::SteerResult

Steer a thread with another user message. Steering a closed thread returns a conflict; steering a running or awaiting thread queues the message.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • message (String)
  • request_options (Cerca::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



214
215
216
217
218
219
220
221
222
223
 
# File 'lib/cerca/resources/threads.rb', line 214

def steer(agent_id, thread_id, params)
  parsed, options = Cerca::ThreadSteerParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["agents/%1$s/threads/%2$s/steer", agent_id, thread_id],
    body: parsed,
    model: Cerca::SteerResult,
    options: options
  )
end