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:



292
293
294
 
# File 'lib/cerca/resources/threads.rb', line 292

def initialize(client:)
  @client = client
end

Instance Method Details

#activity(agent_id, thread_id, fleet_id: nil, request_options: {}) ⇒ Cerca::Models::ActivityDetail

Fetch compact current and recent activity for a thread without returning transcript content or runtime debug state.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • fleet_id (String) —

    Optional fleet id for index-backed authorization.

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

Returns:

See Also:



124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/cerca/resources/threads.rb', line 124

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

#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:



148
149
150
151
152
153
154
155
 
# File 'lib/cerca/resources/threads.rb', line 148

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:



169
170
171
172
173
174
175
176
 
# File 'lib/cerca/resources/threads.rb', line 169

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:



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

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:



95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/cerca/resources/threads.rb', line 95

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

#list_messages(agent_id, thread_id, cursor: nil, fleet_id: nil, limit: nil, request_options: {}) ⇒ Cerca::Internal::ThreadMessagesCursorPage<Cerca::Models::Message>

List a bounded page of transcript messages for a thread, newest first. Use the returned ‘cursor` to page older messages.

Parameters:

  • agent_id (String)
  • thread_id (String)
  • cursor (String) —

    Cursor returned by a previous thread messages response.

  • fleet_id (String) —

    Optional fleet id for index-backed authorization.

  • limit (String) —

    Maximum number of messages to include, capped at 500.

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

Returns:

See Also:



219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/cerca/resources/threads.rb', line 219

def list_messages(agent_id, thread_id, params = {})
  parsed, options = Cerca::ThreadListMessagesParams.dump_request(params)
  query = Cerca::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["agents/%1$s/threads/%2$s/messages", agent_id, thread_id],
    query: query.transform_keys(fleet_id: "fleetId"),
    page: Cerca::Internal::ThreadMessagesCursorPage,
    model: Cerca::Message,
    options: options
  )
end

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

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

Retrieve thread

Parameters:

Returns:

See Also:



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/cerca/resources/threads.rb', line 61

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:



254
255
256
257
258
259
260
261
262
263
 
# File 'lib/cerca/resources/threads.rb', line 254

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:



278
279
280
281
282
283
284
285
286
287
 
# File 'lib/cerca/resources/threads.rb', line 278

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