Class: Handinger::Resources::Workers

Inherits:
Object
  • Object
show all
Defined in:
lib/handinger/resources/workers.rb,
lib/handinger/resources/workers/webhooks.rb,
lib/handinger/resources/workers/schedules.rb

Overview

Create, retrieve, and manage agent worker templates.

Defined Under Namespace

Classes: Schedules, Webhooks

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Workers

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 Workers.

Parameters:



163
164
165
166
167
 
# File 'lib/handinger/resources/workers.rb', line 163

def initialize(client:)
  @client = client
  @schedules = Handinger::Resources::Workers::Schedules.new(client: client)
  @webhooks = Handinger::Resources::Workers::Webhooks.new(client: client)
end

Instance Attribute Details

#schedules ⇒ Handinger::Resources::Workers::Schedules (readonly)

Manage future and recurring worker tasks.

Returns:



9
10
11
 
# File 'lib/handinger/resources/workers.rb', line 9

def schedules
  @schedules
end

#webhooks ⇒ Handinger::Resources::Workers::Webhooks (readonly)

Configure outbound webhooks delivered when a worker’s tasks complete.

Returns:



13
14
15
 
# File 'lib/handinger/resources/workers.rb', line 13

def webhooks
  @webhooks
end

Instance Method Details

#create(instructions: nil, output_schema: nil, prompt: nil, summary: nil, title: nil, visibility: nil, request_options: {}) ⇒ Handinger::Models::WorkerTemplate

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

Create a new worker. The worker is a reusable agent template; tasks are runs against this template. Use ‘POST /tasks` to actually run the agent.

Parameters:

  • instructions (String) —

    Persistent system prompt the worker uses for every task it runs.

  • output_schema (Hash{Symbol=>Object}) —

    Optional JSON Schema (Draft-07) describing the structured object the worker must

  • prompt (String) —

    Natural-language description of the worker to use for AI-generated instructions

  • summary (String) —

    Short one-line description of the worker’s purpose. Auto-generated when omitted

  • title (String) —

    Optional display name. When omitted, Handinger assigns a random dog-themed name.

  • visibility (Symbol, Handinger::Models::CreateWorker::Visibility) —

    ‘public` (default) is visible to all org members. `private` is only visible to i

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

Returns:

See Also:



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/handinger/resources/workers.rb', line 40

def create(params = {})
  parsed, options = Handinger::WorkerCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "api/workers",
    body: parsed,
    model: Handinger::WorkerTemplate,
    options: options
  )
end

#delete(worker_id, request_options: {}) ⇒ Handinger::Models::DeleteWorkerResponse

Soft-delete a worker template so it no longer appears in list or retrieve endpoints. Tasks, turns, files, schedules, and integrations remain in the database for analytics. Only the worker creator can delete a worker.

Parameters:

  • worker_id (String) —

    Worker id returned by the create worker endpoint.

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

Returns:

See Also:



131
132
133
134
135
136
137
138
 
# File 'lib/handinger/resources/workers.rb', line 131

def delete(worker_id, params = {})
  @client.request(
    method: :delete,
    path: ["api/workers/%1$s", worker_id],
    model: Handinger::DeleteWorkerResponse,
    options: params[:request_options]
  )
end

#retrieve(worker_id, stream: nil, request_options: {}) ⇒ Handinger::Models::Worker

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

Retrieve the current worker state and messages from its most recent task. Returns a JSON worker object by default, or a server-sent event stream when ‘stream=true`.

Parameters:

Returns:

See Also:



69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/handinger/resources/workers.rb', line 69

def retrieve(worker_id, params = {})
  parsed, options = Handinger::WorkerRetrieveParams.dump_request(params)
  query = Handinger::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["api/workers/%1$s", worker_id],
    query: query,
    model: Handinger::Worker,
    options: options
  )
end

#retrieve_email(worker_id, request_options: {}) ⇒ Handinger::Models::WorkerRetrieveEmailResponse

Retrieve the inbound email address for a worker.

Parameters:

  • worker_id (String) —

    Worker id returned by the create worker endpoint.

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

Returns:

See Also:



151
152
153
154
155
156
157
158
 
# File 'lib/handinger/resources/workers.rb', line 151

def retrieve_email(worker_id, params = {})
  @client.request(
    method: :get,
    path: ["api/workers/%1$s/email", worker_id],
    model: Handinger::Models::WorkerRetrieveEmailResponse,
    options: params[:request_options]
  )
end

#update(worker_id, instructions: nil, output_schema: nil, summary: nil, title: nil, visibility: nil, request_options: {}) ⇒ Handinger::Models::WorkerTemplate

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

Update a worker’s instructions, title, summary, visibility, or output schema. Only the fields you send are changed; omitted fields keep their current values. Only the worker creator can update a worker.

Parameters:

  • worker_id (String) —

    Worker id returned by the create worker endpoint.

  • instructions (String) —

    Replaces the persistent system prompt. Subsequent tasks pick up the new instruct

  • output_schema (Hash{Symbol=>Object}, nil) —

    Replace the worker’s structured output schema. Pass ‘null` to clear it and retur

  • summary (String) —

    Replaces the worker’s short one-line summary.

  • title (String) —

    New display name for the worker.

  • visibility (Symbol, Handinger::Models::UpdateWorker::Visibility) —

    Change visibility between ‘public` (any org member can run tasks) and `private`

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

Returns:

See Also:



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/handinger/resources/workers.rb', line 107

def update(worker_id, params = {})
  parsed, options = Handinger::WorkerUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["api/workers/%1$s", worker_id],
    body: parsed,
    model: Handinger::WorkerTemplate,
    options: options
  )
end