Skip to content
Handinger
Get started
API Reference
Workers

Create a worker template

workers.create(**kwargs) -> WorkerTemplate { id, created_at, instructions, 8 more }
POST/api/workers

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.

ParametersExpand Collapse
instructions: String

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

maxLength20000
output_schema: Hash[Symbol, untyped]

Optional JSON Schema (Draft-07) describing the structured object the worker must produce. When set, every task response is validated against the schema and exposed as structuredOutput.

prompt: String

Natural-language description of the worker to use for AI-generated instructions when instructions is omitted.

maxLength10000
summary: String

Short one-line description of the worker’s purpose. Auto-generated when omitted and a prompt is provided.

maxLength80
title: String

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

minLength1
maxLength200
visibility: :public | :private

public (default) is visible to all org members. private is only visible to invited members.

One of the following:
:public
:private
ReturnsExpand Collapse
class WorkerTemplate { id, created_at, instructions, 8 more }
id: String
created_at: String
instructions: String
organization_id: String
output_schema: Hash[Symbol, untyped]
summary: String
title: String
updated_at: String
url: String

Web URL of the worker in the Handinger dashboard.

user_id: String
visibility: :public | :private
One of the following:
:public
:private

Create a worker template

require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

worker_template = handinger.workers.create

puts(worker_template)
{
  "id": "id",
  "createdAt": "createdAt",
  "instructions": "instructions",
  "organizationId": "organizationId",
  "outputSchema": {
    "foo": "bar"
  },
  "summary": "summary",
  "title": "title",
  "updatedAt": "updatedAt",
  "url": "https://v3.handinger.com/worker/wrk_vk81XUHKHG-qr4",
  "userId": "userId",
  "visibility": "public"
}
Returns Examples
{
  "id": "id",
  "createdAt": "createdAt",
  "instructions": "instructions",
  "organizationId": "organizationId",
  "outputSchema": {
    "foo": "bar"
  },
  "summary": "summary",
  "title": "title",
  "updatedAt": "updatedAt",
  "url": "https://v3.handinger.com/worker/wrk_vk81XUHKHG-qr4",
  "userId": "userId",
  "visibility": "public"
}