# Workers ## Create a worker `workers.create(WorkerCreateParams**kwargs) -> Worker` **post** `/api/workers` Create a new agent worker and start it with the supplied instruction. ### Parameters - `input: str` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream: Optional[bool]` ### Returns - `class Worker: …` - `id: str` - `created_at: Optional[int]` - `error: None` - `files: List[File]` - `filename: Optional[str]` - `media_type: str` - `url: str` - `incomplete_details: None` - `messages: List[object]` - `metadata: Dict[str, object]` - `object: Literal["worker"]` - `"worker"` - `output: List[Output]` - `id: str` - `content: List[OutputContent]` - `text: str` - `type: Literal["output_text"]` - `"output_text"` - `role: Literal["assistant"]` - `"assistant"` - `status: Literal["completed"]` - `"completed"` - `type: Literal["message"]` - `"message"` - `output_text: str` - `running: bool` - `sources: List[Source]` - `id: str` - `title: Optional[str]` - `type: Literal["url"]` - `"url"` - `url: str` - `status: Literal["running", "completed", "pending"]` - `"running"` - `"completed"` - `"pending"` - `costs: Optional[Costs]` - `internal_cost_usd: float` - `model_cost_usd: float` - `sandbox_cost_usd: float` - `tool_cost_usd: float` - `usage: Optional[Usage]` - `cache_read_tokens: int` - `cache_write_tokens: int` - `cost_usd: float` - `input_tokens: int` - `output_tokens: int` - `reasoning_tokens: int` - `steps: int` - `total_tokens: int` - `credits: Optional[int]` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) worker = client.workers.create( input="x", ) print(worker.id) ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Retrieve a worker `workers.retrieve(strworker_id, WorkerRetrieveParams**kwargs) -> Worker` **get** `/api/workers/{workerId}` Retrieve the current worker state. Pass stream=true or request text/event-stream to subscribe to updates. ### Parameters - `worker_id: str` - `stream: Optional[bool]` Return a server-sent event stream instead of JSON. ### Returns - `class Worker: …` - `id: str` - `created_at: Optional[int]` - `error: None` - `files: List[File]` - `filename: Optional[str]` - `media_type: str` - `url: str` - `incomplete_details: None` - `messages: List[object]` - `metadata: Dict[str, object]` - `object: Literal["worker"]` - `"worker"` - `output: List[Output]` - `id: str` - `content: List[OutputContent]` - `text: str` - `type: Literal["output_text"]` - `"output_text"` - `role: Literal["assistant"]` - `"assistant"` - `status: Literal["completed"]` - `"completed"` - `type: Literal["message"]` - `"message"` - `output_text: str` - `running: bool` - `sources: List[Source]` - `id: str` - `title: Optional[str]` - `type: Literal["url"]` - `"url"` - `url: str` - `status: Literal["running", "completed", "pending"]` - `"running"` - `"completed"` - `"pending"` - `costs: Optional[Costs]` - `internal_cost_usd: float` - `model_cost_usd: float` - `sandbox_cost_usd: float` - `tool_cost_usd: float` - `usage: Optional[Usage]` - `cache_read_tokens: int` - `cache_write_tokens: int` - `cost_usd: float` - `input_tokens: int` - `output_tokens: int` - `reasoning_tokens: int` - `steps: int` - `total_tokens: int` - `credits: Optional[int]` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) worker = client.workers.retrieve( worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ) print(worker.id) ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Continue a worker `workers.continue_(strworker_id, WorkerContinueParams**kwargs) -> Worker` **post** `/api/workers/{workerId}` Send another instruction to an existing worker. ### Parameters - `worker_id: str` - `input: str` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream: Optional[bool]` ### Returns - `class Worker: …` - `id: str` - `created_at: Optional[int]` - `error: None` - `files: List[File]` - `filename: Optional[str]` - `media_type: str` - `url: str` - `incomplete_details: None` - `messages: List[object]` - `metadata: Dict[str, object]` - `object: Literal["worker"]` - `"worker"` - `output: List[Output]` - `id: str` - `content: List[OutputContent]` - `text: str` - `type: Literal["output_text"]` - `"output_text"` - `role: Literal["assistant"]` - `"assistant"` - `status: Literal["completed"]` - `"completed"` - `type: Literal["message"]` - `"message"` - `output_text: str` - `running: bool` - `sources: List[Source]` - `id: str` - `title: Optional[str]` - `type: Literal["url"]` - `"url"` - `url: str` - `status: Literal["running", "completed", "pending"]` - `"running"` - `"completed"` - `"pending"` - `costs: Optional[Costs]` - `internal_cost_usd: float` - `model_cost_usd: float` - `sandbox_cost_usd: float` - `tool_cost_usd: float` - `usage: Optional[Usage]` - `cache_read_tokens: int` - `cache_write_tokens: int` - `cost_usd: float` - `input_tokens: int` - `output_tokens: int` - `reasoning_tokens: int` - `steps: int` - `total_tokens: int` - `credits: Optional[int]` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) worker = client.workers.continue_( worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", input="x", ) print(worker.id) ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Stream worker updates `workers.stream_updates(strworker_id) -> WorkerStreamUpdatesResponse` **get** `/api/workers/{workerId}/stream` Subscribe to a worker using server-sent events. ### Parameters - `worker_id: str` ### Returns - `str` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) for worker in client.workers.stream_updates( "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ): print(worker) ``` ## Retrieve a worker email address `workers.retrieve_email(strworker_id) -> WorkerRetrieveEmailResponse` **get** `/api/workers/{workerId}/email` Retrieve the inbound email address for a worker. ### Parameters - `worker_id: str` ### Returns - `str` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) response = client.workers.retrieve_email( "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ) print(response) ``` #### Response ```json "string" ``` ## Retrieve a worker file `workers.retrieve_file(strfile_path, WorkerRetrieveFileParams**kwargs) -> BinaryResponseContent` **get** `/api/workers/{workerId}/files/{filePath}` Retrieve a file published from a worker workspace. The runtime route accepts nested paths after /files/. ### Parameters - `worker_id: str` - `file_path: str` ### Returns - `BinaryResponseContent` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) response = client.workers.retrieve_file( file_path="scratchpad/plan.md", worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ) print(response) content = response.read() print(content) ``` ## Domain Types ### Create Worker - `class CreateWorker: …` - `input: str` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream: Optional[bool]` ### Worker - `class Worker: …` - `id: str` - `created_at: Optional[int]` - `error: None` - `files: List[File]` - `filename: Optional[str]` - `media_type: str` - `url: str` - `incomplete_details: None` - `messages: List[object]` - `metadata: Dict[str, object]` - `object: Literal["worker"]` - `"worker"` - `output: List[Output]` - `id: str` - `content: List[OutputContent]` - `text: str` - `type: Literal["output_text"]` - `"output_text"` - `role: Literal["assistant"]` - `"assistant"` - `status: Literal["completed"]` - `"completed"` - `type: Literal["message"]` - `"message"` - `output_text: str` - `running: bool` - `sources: List[Source]` - `id: str` - `title: Optional[str]` - `type: Literal["url"]` - `"url"` - `url: str` - `status: Literal["running", "completed", "pending"]` - `"running"` - `"completed"` - `"pending"` - `costs: Optional[Costs]` - `internal_cost_usd: float` - `model_cost_usd: float` - `sandbox_cost_usd: float` - `tool_cost_usd: float` - `usage: Optional[Usage]` - `cache_read_tokens: int` - `cache_write_tokens: int` - `cost_usd: float` - `input_tokens: int` - `output_tokens: int` - `reasoning_tokens: int` - `steps: int` - `total_tokens: int` - `credits: Optional[int]` ### Worker Stream Updates Response - `str` ### Worker Retrieve Email Response - `str` # Schedules ## List worker schedules `workers.schedules.list(strworker_id) -> ScheduleListResponse` **get** `/api/workers/{workerId}/schedules` List scheduled tasks for a worker. ### Parameters - `worker_id: str` ### Returns - `class ScheduleListResponse: …` - `schedules: List[WorkerSchedule]` - `class UnionMember0: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `next_run_at: datetime` - `type: Literal["scheduled"]` - `"scheduled"` - `class UnionMember1: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delay_in_seconds: int` - `input: str` - `next_run_at: datetime` - `type: Literal["delayed"]` - `"delayed"` - `class UnionMember2: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: str` - `input: str` - `next_run_at: datetime` - `type: Literal["cron"]` - `"cron"` - `class UnionMember3: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `interval_seconds: int` - `next_run_at: datetime` - `type: Literal["interval"]` - `"interval"` - `worker_id: str` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) schedules = client.workers.schedules.list( "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ) print(schedules.schedules) ``` #### Response ```json { "schedules": [ { "id": "id", "budget": "low", "input": "input", "nextRunAt": "2019-12-27T18:11:19.117Z", "type": "scheduled" } ], "workerId": "workerId" } ``` ## Create a worker schedule `workers.schedules.create(strworker_id, ScheduleCreateParams**kwargs) -> WorkerSchedule` **post** `/api/workers/{workerId}/schedules` Schedule a worker instruction for a future or recurring run. ### Parameters - `worker_id: str` - `input: str` - `when: When` - `class WhenUnionMember0: …` - `date: Union[str, datetime]` - `type: Literal["scheduled"]` - `"scheduled"` - `class WhenUnionMember1: …` - `delay_in_seconds: int` - `type: Literal["delayed"]` - `"delayed"` - `class WhenUnionMember2: …` - `cron: str` - `type: Literal["cron"]` - `"cron"` - `class WhenUnionMember3: …` - `interval_seconds: int` - `type: Literal["interval"]` - `"interval"` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` ### Returns - `WorkerSchedule` - `class UnionMember0: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `next_run_at: datetime` - `type: Literal["scheduled"]` - `"scheduled"` - `class UnionMember1: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delay_in_seconds: int` - `input: str` - `next_run_at: datetime` - `type: Literal["delayed"]` - `"delayed"` - `class UnionMember2: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: str` - `input: str` - `next_run_at: datetime` - `type: Literal["cron"]` - `"cron"` - `class UnionMember3: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `interval_seconds: int` - `next_run_at: datetime` - `type: Literal["interval"]` - `"interval"` ### Example ```python import os from datetime import datetime from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) worker_schedule = client.workers.schedules.create( worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", input="x", when={ "date": datetime.fromisoformat("2019-12-27T18:11:19.117"), "type": "scheduled", }, ) print(worker_schedule) ``` #### Response ```json { "id": "id", "budget": "low", "input": "input", "nextRunAt": "2019-12-27T18:11:19.117Z", "type": "scheduled" } ``` ## Cancel a worker schedule `workers.schedules.cancel(strschedule_id, ScheduleCancelParams**kwargs) -> ScheduleCancelResponse` **delete** `/api/workers/{workerId}/schedules/{scheduleId}` Cancel a scheduled task for a worker. ### Parameters - `worker_id: str` - `schedule_id: str` ### Returns - `class ScheduleCancelResponse: …` - `cancelled: bool` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) response = client.workers.schedules.cancel( schedule_id="sch_01HZY31W2SZJ8MJ2FQTR3M1K9D", worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM", ) print(response.cancelled) ``` #### Response ```json { "cancelled": true } ``` ## Domain Types ### Worker Schedule - `WorkerSchedule` - `class UnionMember0: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `next_run_at: datetime` - `type: Literal["scheduled"]` - `"scheduled"` - `class UnionMember1: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delay_in_seconds: int` - `input: str` - `next_run_at: datetime` - `type: Literal["delayed"]` - `"delayed"` - `class UnionMember2: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: str` - `input: str` - `next_run_at: datetime` - `type: Literal["cron"]` - `"cron"` - `class UnionMember3: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `interval_seconds: int` - `next_run_at: datetime` - `type: Literal["interval"]` - `"interval"` ### Schedule List Response - `class ScheduleListResponse: …` - `schedules: List[WorkerSchedule]` - `class UnionMember0: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `next_run_at: datetime` - `type: Literal["scheduled"]` - `"scheduled"` - `class UnionMember1: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delay_in_seconds: int` - `input: str` - `next_run_at: datetime` - `type: Literal["delayed"]` - `"delayed"` - `class UnionMember2: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: str` - `input: str` - `next_run_at: datetime` - `type: Literal["cron"]` - `"cron"` - `class UnionMember3: …` - `id: str` - `budget: Literal["low", "standard", "high", "unlimited"]` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: str` - `interval_seconds: int` - `next_run_at: datetime` - `type: Literal["interval"]` - `"interval"` - `worker_id: str` ### Schedule Cancel Response - `class ScheduleCancelResponse: …` - `cancelled: bool`