human_dispatch_task
Assign tasks to human workers by specifying description, category, location, budget, and proof requirements. The system routes to the best available provider or manual fallback.
Instructions
Dispatch a task to a human worker via the best available backend service.
This is the primary tool for sending work to humans. You describe what needs to be done, and the system routes it to the most appropriate registered webhook provider based on category, task type, region, and budget. If no providers match or accept, the task falls through to the manual fallback.
Register providers first with human_register_provider, then dispatch tasks to them.
PARAMETERS:
description: What the human should do. Be specific about location, timing, and deliverables.
category: Task category (errand, photo_video, data_collection, verification, delivery, digital_micro, in_person, custom)
task_type: physical (requires presence), digital (remote), or hybrid (both)
location: Where to perform the task (required for physical tasks). Include address or coordinates.
budget: Maximum USD to pay. Different providers have different ranges.
deadline: When it must be done, with urgency level.
proof_required: What evidence the worker must submit (photo, video, gps_checkin, text_report, receipt, signature).
quality_sla: low (fast/cheap), medium (default), high (verified workers, multiple proofs).
preferred_backends: Optional ordered list of backends to try first (webhook_provider, manual).
fallback_chain: Optional ordered fallback list if preferred backends fail.
metadata: Optional key-value pairs for your own tracking.
EXAMPLES:
Photo task: { description: "Take a photo of the menu board at the Starbucks on 5th Ave and 42nd St, NYC", category: "photo_video", task_type: "physical", location: { address: "5th Ave & 42nd St, New York, NY" }, budget: { max_usd: 15, currency: "USD" }, deadline: { complete_by: "2027-01-15T18:00:00Z", urgency: "medium" }, proof_required: ["photo", "gps_checkin"], quality_sla: "medium" }
Data collection: { description: "Count the number of electric vehicle charging stations within 1km of Times Square", category: "data_collection", task_type: "physical", location: { address: "Times Square, NYC", radius_km: 1 }, budget: { max_usd: 25, currency: "USD" }, deadline: { complete_by: "2027-01-20T00:00:00Z", urgency: "low" }, proof_required: ["text_report", "photo"], quality_sla: "high" }
Digital microtask: { description: "Transcribe the handwritten text in the attached image to typed text", category: "digital_micro", task_type: "digital", budget: { max_usd: 2, currency: "USD" }, deadline: { complete_by: "2027-01-16T00:00:00Z", urgency: "medium" }, proof_required: ["text_report"], quality_sla: "low" }
DON'T USE WHEN:
The task can be done by an AI (use an AI tool instead)
You need instant results (humans take minutes to hours)
No providers are registered (use human_register_provider first, or rely on manual fallback)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget | Yes | Budget constraints for the task | |
| category | Yes | Category of the task — determines which backends are best suited | |
| deadline | Yes | When the task needs to be completed | |
| location | No | Where the task should be performed. Required for physical tasks. Set to null or omit for digital tasks. | |
| metadata | No | Arbitrary key-value pairs for your own tracking (e.g. {'order_id': '12345', 'agent_name': 'my-bot'}) | |
| task_type | Yes | Whether the task requires physical presence, is digital-only, or both | |
| description | Yes | Clear, detailed description of what the human worker should do. Be specific about location, timing, and expected output. Example: 'Take a photo of the menu board at the Starbucks on 5th Ave and 42nd St, NYC' | |
| quality_sla | Yes | Quality/speed tradeoff: low=fastest/cheapest, medium=default, high=verified workers with multi-proof | |
| fallback_chain | No | Ordered list of fallback backends if the preferred ones fail. The 'manual' backend is always available as a last resort. | |
| proof_required | Yes | Types of proof the worker must submit upon completion. At least one is required. Example: ['photo', 'gps_checkin'] | |
| idempotency_key | No | Optional client-supplied key to dedupe retried submissions. If a task with the same key was created within the last hour, the existing task is returned instead of a duplicate. Example: 'order-12345-attempt-1' | |
| preferred_backends | No | Preferred backend services to route this task to, tried in order. If omitted, the router picks the best backend automatically. |