Class: WorkOS::Agents

Inherits:
Object
  • Object
show all
Defined in:
lib/workos/agents.rb

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Agents

Returns a new instance of Agents.



9
10
11
# File 'lib/workos/agents.rb', line 9

def initialize(client)
  @client = client
end

Instance Method Details

#create_blueprint(name:, description: nil, permissions: nil, invocable_by: nil, session_settings: nil, request_options: {}) ⇒ WorkOS::AgentBlueprint

Create an agent blueprint

Parameters:

  • name (String)

    Human-readable name of the agent blueprint.

  • description (String, nil) (defaults to: nil)

    Human-readable description of the agent blueprint.

  • permissions (Array<String>, nil) (defaults to: nil)

    Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment.

  • invocable_by (WorkOS::AgentBlueprintsCreateRequestInvocableBy, nil) (defaults to: nil)

    Who may mint sessions from this blueprint.

  • session_settings (WorkOS::AgentBlueprintsCreateRequestSessionSetting, nil) (defaults to: nil)

    Token and session lifetimes for sessions minted from this blueprint.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# File 'lib/workos/agents.rb', line 65

def create_blueprint(
  name:,
  description: nil,
  permissions: nil,
  invocable_by: nil,
  session_settings: nil,
  request_options: {}
)
  body = {
    "name" => name,
    "description" => description,
    "permissions" => permissions,
    "invocable_by" => invocable_by,
    "session_settings" => session_settings
  }.compact
  response = @client.request(
    method: :post,
    path: "/agents/blueprints",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::AgentBlueprint.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#create_blueprint_token(agent_blueprint_id:, type:, user_access_token: nil, intent: nil, organization_id: nil, agent_access_token: nil, refresh_token: nil, request_options: {}) ⇒ WorkOS::AgentToken

Mint an agent token

Parameters:

  • agent_blueprint_id (String)

    The unique ID of the agent blueprint.

  • type (WorkOS::Types::AgentBlueprintsTokenMintTokenRequestType)

    How the session is minted: user_delegated, autonomous, agent_delegated, or refresh.

  • user_access_token (String, nil) (defaults to: nil)

    The access token of the user delegating to the agent. The token identifies the user and organization; effective permissions are resolved server-side.

  • intent (String, nil) (defaults to: nil)

    Optional caller-supplied context, echoed as an object with a text field in the intent claim of the minted access token.

  • organization_id (String, nil) (defaults to: nil)

    The organization the agent acts within when operating as itself.

  • agent_access_token (String, nil) (defaults to: nil)

    The agent's own access token to exchange for a new session on the same instance. The token must have been minted from this blueprint; permissions are re-derived from current authority.

  • refresh_token (String, nil) (defaults to: nil)

    The refresh token issued with a previous agent access token. Refresh tokens are single-use: each refresh rotates it.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
# File 'lib/workos/agents.rb', line 175

def create_blueprint_token(
  agent_blueprint_id:,
  type:,
  user_access_token: nil,
  intent: nil,
  organization_id: nil,
  agent_access_token: nil,
  refresh_token: nil,
  request_options: {}
)
  body = {
    "type" => type,
    "user_access_token" => user_access_token,
    "intent" => intent,
    "organization_id" => organization_id,
    "agent_access_token" => agent_access_token,
    "refresh_token" => refresh_token
  }.compact
  response = @client.request(
    method: :post,
    path: "/agents/blueprints/#{WorkOS::Util.encode_path(agent_blueprint_id)}/tokens",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::AgentToken.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#create_validate(type:, credential:, audience: nil, request_options: {}) ⇒ WorkOS::AgentCredentialValidation

Validate an agent credential

Parameters:

  • type (WorkOS::Types::AgentAdminValidateCredentialRequestType)

    The kind of credential being validated — an agent API key or an agent access token.

  • credential (String)

    The credential value to validate: the API key value for api_key, or the access token (JWT) for access_token.

  • audience (String, nil) (defaults to: nil)

    When provided, the access token's aud claim is verified against this value. Tokens issued for a different resource are rejected.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
# File 'lib/workos/agents.rb', line 268

def create_validate(
  type:,
  credential:,
  audience: nil,
  request_options: {}
)
  body = {
    "type" => type,
    "credential" => credential,
    "audience" => audience
  }.compact
  response = @client.request(
    method: :post,
    path: "/agents/credentials/validate",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::AgentCredentialValidation.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#delete_blueprint(agent_blueprint_id:, request_options: {}) ⇒ void

This method returns an undefined value.

Delete an agent blueprint

Parameters:

  • agent_blueprint_id (String)

    The unique ID of the agent blueprint.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)



152
153
154
155
156
157
158
159
160
161
162
163
# File 'lib/workos/agents.rb', line 152

def delete_blueprint(
  agent_blueprint_id:,
  request_options: {}
)
  @client.request(
    method: :delete,
    path: "/agents/blueprints/#{WorkOS::Util.encode_path(agent_blueprint_id)}",
    auth: true,
    request_options: request_options
  )
  nil
end

#delete_instance(agent_instance_id:, request_options: {}) ⇒ void

This method returns an undefined value.

Delete an agent instance

Parameters:

  • agent_instance_id (String)

    The unique ID of the agent instance.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)



385
386
387
388
389
390
391
392
393
394
395
396
# File 'lib/workos/agents.rb', line 385

def delete_instance(
  agent_instance_id:,
  request_options: {}
)
  @client.request(
    method: :delete,
    path: "/agents/instances/#{WorkOS::Util.encode_path(agent_instance_id)}",
    auth: true,
    request_options: request_options
  )
  nil
end

#get_blueprint(agent_blueprint_id:, request_options: {}) ⇒ WorkOS::AgentBlueprint

Get an agent blueprint

Parameters:

  • agent_blueprint_id (String)

    The unique ID of the agent blueprint.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
# File 'lib/workos/agents.rb', line 96

def get_blueprint(
  agent_blueprint_id:,
  request_options: {}
)
  response = @client.request(
    method: :get,
    path: "/agents/blueprints/#{WorkOS::Util.encode_path(agent_blueprint_id)}",
    auth: true,
    request_options: request_options
  )
  result = WorkOS::AgentBlueprint.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#get_instance(agent_instance_id:, request_options: {}) ⇒ WorkOS::AgentInstance

Get an agent instance

Parameters:

  • agent_instance_id (String)

    The unique ID of the agent instance.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
# File 'lib/workos/agents.rb', line 366

def get_instance(
  agent_instance_id:,
  request_options: {}
)
  response = @client.request(
    method: :get,
    path: "/agents/instances/#{WorkOS::Util.encode_path(agent_instance_id)}",
    auth: true,
    request_options: request_options
  )
  result = WorkOS::AgentInstance.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#get_registration(id:, request_options: {}) ⇒ WorkOS::AgentRegistration

Get an agent registration

Parameters:

  • id (String)

    The unique ID of the agent registration.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



295
296
297
298
299
300
301
302
303
304
305
306
307
308
# File 'lib/workos/agents.rb', line 295

def get_registration(
  id:,
  request_options: {}
)
  response = @client.request(
    method: :get,
    path: "/agents/registrations/#{WorkOS::Util.encode_path(id)}",
    auth: true,
    request_options: request_options
  )
  result = WorkOS::AgentRegistration.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#get_session(agent_instance_session_id:, request_options: {}) ⇒ WorkOS::AgentInstanceSession

Get an agent instance session

Parameters:

  • agent_instance_session_id (String)

    The unique ID of the agent instance session.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



458
459
460
461
462
463
464
465
466
467
468
469
470
471
# File 'lib/workos/agents.rb', line 458

def get_session(
  agent_instance_session_id:,
  request_options: {}
)
  response = @client.request(
    method: :get,
    path: "/agents/sessions/#{WorkOS::Util.encode_path(agent_instance_session_id)}",
    auth: true,
    request_options: request_options
  )
  result = WorkOS::AgentInstanceSession.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#list_blueprints(before: nil, after: nil, limit: 10, order: "desc", request_options: {}) ⇒ WorkOS::Types::ListStruct<WorkOS::AgentBlueprint>

List agent blueprints

Parameters:

  • before (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".

  • after (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".

  • limit (Integer, nil) (defaults to: 10)

    Upper limit on the number of objects to return, between 1 and 100.

  • order (WorkOS::Types::PaginationOrder, nil) (defaults to: "desc")

    Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records).

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# File 'lib/workos/agents.rb', line 20

def list_blueprints(
  before: nil,
  after: nil,
  limit: 10,
  order: "desc",
  request_options: {}
)
  params = {
    "before" => before,
    "after" => after,
    "limit" => limit,
    "order" => order
  }.compact
  response = @client.request(
    method: :get,
    path: "/agents/blueprints",
    auth: true,
    params: params,
    request_options: request_options
  )
  fetch_next = ->(cursor) {
    list_blueprints(
      before: before,
      after: cursor,
      limit: limit,
      order: order,
      request_options: request_options
    )
  }
  WorkOS::Types::ListStruct.from_response(
    response,
    model: WorkOS::AgentBlueprint,
    filters: {before: before, limit: limit, order: order},
    fetch_next: fetch_next
  )
end

#list_instances(before: nil, after: nil, limit: 10, order: "desc", organization_id: nil, agent_blueprint_id: nil, request_options: {}) ⇒ WorkOS::Types::ListStruct<WorkOS::AgentInstance>

List agent instances

Parameters:

  • before (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".

  • after (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".

  • limit (Integer, nil) (defaults to: 10)

    Upper limit on the number of objects to return, between 1 and 100.

  • order (WorkOS::Types::PaginationOrder, nil) (defaults to: "desc")

    Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records).

  • organization_id (String, nil) (defaults to: nil)

    Only return instances acting within this organization.

  • agent_blueprint_id (String, nil) (defaults to: nil)

    Only return instances minted from this blueprint.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
# File 'lib/workos/agents.rb', line 319

def list_instances(
  before: nil,
  after: nil,
  limit: 10,
  order: "desc",
  organization_id: nil,
  agent_blueprint_id: nil,
  request_options: {}
)
  params = {
    "before" => before,
    "after" => after,
    "limit" => limit,
    "order" => order,
    "organization_id" => organization_id,
    "agent_blueprint_id" => agent_blueprint_id
  }.compact
  response = @client.request(
    method: :get,
    path: "/agents/instances",
    auth: true,
    params: params,
    request_options: request_options
  )
  fetch_next = ->(cursor) {
    list_instances(
      before: before,
      after: cursor,
      limit: limit,
      order: order,
      organization_id: organization_id,
      agent_blueprint_id: agent_blueprint_id,
      request_options: request_options
    )
  }
  WorkOS::Types::ListStruct.from_response(
    response,
    model: WorkOS::AgentInstance,
    filters: {before: before, limit: limit, order: order, organization_id: organization_id, agent_blueprint_id: agent_blueprint_id},
    fetch_next: fetch_next
  )
end

#list_sessions(before: nil, after: nil, limit: 10, order: "desc", organization_id: nil, agent_blueprint_id: nil, agent_instance_id: nil, request_options: {}) ⇒ WorkOS::Types::ListStruct<WorkOS::AgentInstanceSession>

List agent instance sessions

Parameters:

  • before (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include before="obj_123" to fetch a new batch of objects before "obj_123".

  • after (String, nil) (defaults to: nil)

    An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with "obj_123", your subsequent call can include after="obj_123" to fetch a new batch of objects after "obj_123".

  • limit (Integer, nil) (defaults to: 10)

    Upper limit on the number of objects to return, between 1 and 100.

  • order (WorkOS::Types::PaginationOrder, nil) (defaults to: "desc")

    Order the results by the creation time. Supported values are "asc" (ascending), "desc" (descending), and "normal" (descending with reversed cursor semantics where before fetches older records and after fetches newer records).

  • organization_id (String, nil) (defaults to: nil)

    Only return sessions of instances acting within this organization.

  • agent_blueprint_id (String, nil) (defaults to: nil)

    Only return sessions of instances minted from this blueprint.

  • agent_instance_id (String, nil) (defaults to: nil)

    Only return sessions belonging to this agent instance.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
# File 'lib/workos/agents.rb', line 408

def list_sessions(
  before: nil,
  after: nil,
  limit: 10,
  order: "desc",
  organization_id: nil,
  agent_blueprint_id: nil,
  agent_instance_id: nil,
  request_options: {}
)
  params = {
    "before" => before,
    "after" => after,
    "limit" => limit,
    "order" => order,
    "organization_id" => organization_id,
    "agent_blueprint_id" => agent_blueprint_id,
    "agent_instance_id" => agent_instance_id
  }.compact
  response = @client.request(
    method: :get,
    path: "/agents/sessions",
    auth: true,
    params: params,
    request_options: request_options
  )
  fetch_next = ->(cursor) {
    list_sessions(
      before: before,
      after: cursor,
      limit: limit,
      order: order,
      organization_id: organization_id,
      agent_blueprint_id: agent_blueprint_id,
      agent_instance_id: agent_instance_id,
      request_options: request_options
    )
  }
  WorkOS::Types::ListStruct.from_response(
    response,
    model: WorkOS::AgentInstanceSession,
    filters: {before: before, limit: limit, order: order, organization_id: organization_id, agent_blueprint_id: agent_blueprint_id, agent_instance_id: agent_instance_id},
    fetch_next: fetch_next
  )
end

#revoke_session(agent_instance_session_id:, request_options: {}) ⇒ WorkOS::AgentInstanceSession

Revoke an agent instance session

Parameters:

  • agent_instance_session_id (String)

    The unique ID of the agent instance session.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



477
478
479
480
481
482
483
484
485
486
487
488
489
490
# File 'lib/workos/agents.rb', line 477

def revoke_session(
  agent_instance_session_id:,
  request_options: {}
)
  response = @client.request(
    method: :post,
    path: "/agents/sessions/#{WorkOS::Util.encode_path(agent_instance_session_id)}/revoke",
    auth: true,
    request_options: request_options
  )
  result = WorkOS::AgentInstanceSession.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#update_attempts(type:, claim_attempt_token:, user:, organization_id: nil, request_options: {}) ⇒ WorkOS::ClaimViewResponse

Link a claim attempt to an external user

Parameters:

  • type (String)

    The operation to perform on the claim attempt. Currently only link_external_user is supported.

  • claim_attempt_token (String)

    The token identifying the claim attempt.

  • user (WorkOS::AgentAdminLinkClaimAttemptToExternalUserRequestUser)

    The user to attach to the claim attempt, identified by email and external ID.

  • organization_id (String, nil) (defaults to: nil)

    The organization to place the agent in. Required when the user belongs to more than one organization.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
# File 'lib/workos/agents.rb', line 237

def update_attempts(
  type:,
  claim_attempt_token:,
  user:,
  organization_id: nil,
  request_options: {}
)
  body = {
    "type" => type,
    "claim_attempt_token" => claim_attempt_token,
    "user" => user,
    "organization_id" => organization_id
  }.compact
  response = @client.request(
    method: :patch,
    path: "/agents/claims/attempts",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::ClaimViewResponse.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#update_blueprint(agent_blueprint_id:, name: nil, description: WorkOS::OMIT, permissions: nil, invocable_by: nil, session_settings: nil, request_options: {}) ⇒ WorkOS::AgentBlueprint

Update an agent blueprint

Parameters:

  • agent_blueprint_id (String)

    The unique ID of the agent blueprint.

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

    Human-readable name of the agent blueprint.

  • description (String, nil) (defaults to: WorkOS::OMIT)

    Human-readable description of the agent blueprint. Pass null to clear it.

  • permissions (Array<String>, nil) (defaults to: nil)

    Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment.

  • invocable_by (WorkOS::AgentBlueprintsUpdateRequestInvocableBy, nil) (defaults to: nil)

    Who may mint sessions from this blueprint. Omitted lists are left unchanged.

  • session_settings (WorkOS::AgentBlueprintsUpdateRequestSessionSetting, nil) (defaults to: nil)

    Token and session lifetimes for sessions minted from this blueprint. Omitted fields are left unchanged.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
# File 'lib/workos/agents.rb', line 120

def update_blueprint(
  agent_blueprint_id:,
  name: nil,
  description: WorkOS::OMIT,
  permissions: nil,
  invocable_by: nil,
  session_settings: nil,
  request_options: {}
)
  body = {
    "name" => name,
    "permissions" => permissions,
    "invocable_by" => invocable_by,
    "session_settings" => session_settings
  }.compact
  body["description"] = description unless description.equal?(WorkOS::OMIT)
  response = @client.request(
    method: :patch,
    path: "/agents/blueprints/#{WorkOS::Util.encode_path(agent_blueprint_id)}",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::AgentBlueprint.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#validate_blueprint_token(agent_blueprint_id:, agent_access_token:, request_options: {}) ⇒ WorkOS::AgentTokenValidation

Validate an agent token

Parameters:

  • agent_blueprint_id (String)

    The unique ID of the agent blueprint.

  • agent_access_token (String)

    The agent access token (a JWT) to validate.

  • request_options (Hash) (defaults to: {})

    (see WorkOS::Types::RequestOptions)

Returns:



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
# File 'lib/workos/agents.rb', line 210

def validate_blueprint_token(
  agent_blueprint_id:,
  agent_access_token:,
  request_options: {}
)
  body = {
    "agent_access_token" => agent_access_token
  }
  response = @client.request(
    method: :post,
    path: "/agents/blueprints/#{WorkOS::Util.encode_path(agent_blueprint_id)}/tokens/validate",
    auth: true,
    body: body,
    request_options: request_options
  )
  result = WorkOS::AgentTokenValidation.new(response.body)
  result.last_response = WorkOS::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end