HumanTask API Examples

Examples

Examples is the developer surface for one specific problem: show end-to-end patterns for common agent workflows instead of documenting isolated endpoints. The design has to combine ordinary software concerns with physical latency, evidence and money movement.

Photo verification agent

Photo verification agent should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Store stock agent

Store stock agent should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

detect missing physical fact
→ create task
→ wait for task.completed
→ fetch evidence
→ validate required fields
→ continue the agent plan

Property check workflow

Property check workflow is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

detect missing physical fact
→ create task
→ wait for task.completed
→ fetch evidence
→ validate required fields
→ continue the agent plan

Remote-hands recovery

For Remote-hands recovery, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Local research workflow

Local research workflow is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

Design lessons across examples

A production treatment of Design lessons across examples needs both the normal path and the exception path. Human execution is reliable only when the client knows what happens when the environment does not match the request.

Example: Stock Check

A shopping agent identifies a product whose online availability is unreliable. It creates a stock-check task with store, SKU and evidence requirements. When the task completes, it reads the availability field and supporting photo before deciding whether to recommend collection.

Example: Remote Hands

An infrastructure agent detects that a device has stopped responding after software recovery attempts. It creates a tightly scoped reset task with approved physical steps and before-and-after indicator evidence. A failure state triggers escalation to a technician.

Example: Property Evidence

A property workflow needs current exterior conditions for a remote reviewer. It creates a standardized shot list, waits for evidence and stores the media references alongside the property record. The worker does not make an investment recommendation.

Error Model

The HTTP request can succeed while the real-world task cannot. Keep transport errors separate from execution outcomes so applications know whether to retry the API call or change the field task itself.

Production Readiness

Test the unhappy path deliberately: invalid scope, no available supply, delayed completion, missing proof and client retry. Real-world APIs are defined as much by those states as by success.

Common Integration Mistake

Examples should make failure and revision paths visible, not present every field task as a guaranteed success.

Next Step

Implement one examples flow against the canonical task lifecycle, inspect the real payloads and only then generalize the client for more capabilities or locations.

Implementation Notes for Examples

Photo verification agent

When implementing photo verification agent for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Store stock agent

When implementing store stock agent for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Property check workflow

When implementing property check workflow for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Remote-hands recovery

When implementing remote-hands recovery for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Local research workflow

When implementing local research workflow for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Design lessons across examples

When implementing design lessons across examples for Examples, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Test Matrix

A Examples integration should be tested against more than the happy path. Include a valid request, invalid input, duplicate retry, no matching supply, worker exception, incomplete evidence and cancellation where the interface supports it. The result of each test should be observable in the canonical task object so developers can reconcile UI, API and agent behavior.