Build Real-World Human Execution into Your AI Agent

Human Task API for Developers

The Human Task API for Developers documentation exists to orient engineers to the HumanTask API execution model and route them to the right integration surface. Because a single request can dispatch a real person, the interface needs stronger operational semantics than a read-only data API.

What the API represents

For What the API represents, 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.

Choose MCP or REST

A production treatment of Choose MCP or REST 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.

Agent / Application
      ↓
HumanTask API
      ↓
Human task
      ↓
Evidence + status
      ↓
Agent / Application

Core objects

For Core objects, 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.

Agent / Application
      ↓
HumanTask API
      ↓
Human task
      ↓
Evidence + status
      ↓
Agent / Application

Physical-world failure modes

Physical-world failure modes 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.

Security and spend

A production treatment of Security and spend 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.

Start with a narrow workflow

For Start with a narrow workflow, 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.

Architecture Boundary

HumanTask API should be treated as an external execution service, not as an invisible subroutine. The calling system decides that a physical step is necessary, sends a constrained request and remains responsible for the business decision made after evidence returns. This separation keeps the integration understandable when a task is delayed, revised or cannot be completed.

Choosing the First Integration

Start with a workflow where the software already knows the location and required outcome. Avoid beginning with tasks that require negotiation or deep worker judgment. A narrow first integration makes it easier to validate task schemas, evidence storage and operational handling before adding more autonomous behavior.

Production Readiness

Before enabling autonomous task creation, test authentication, idempotency, task cancellation, exception handling, evidence access and spending limits. A developer should be able to answer what happens if the same request is submitted twice, a worker cannot enter the site or evidence is incomplete.

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

A release checklist should cover authentication, idempotency, spend limits, exception states, evidence permissions and reconciliation between events and canonical objects.

Common Integration Mistake

The developer documentation should describe only interfaces that are actually available at launch; planned features must be labeled as planned.

Next Step

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

Implementation Notes for Human Task API for Developers

What the API represents

When implementing what the api represents for Human Task API for Developers, 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.

Choose MCP or REST

When implementing choose mcp or rest for Human Task API for Developers, 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.

Core objects

When implementing core objects for Human Task API for Developers, 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.

Physical-world failure modes

When implementing physical-world failure modes for Human Task API for Developers, 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.

Security and spend

When implementing security and spend for Human Task API for Developers, 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.

Start with a narrow workflow

When implementing start with a narrow workflow for Human Task API for Developers, 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 Human Task API for Developers 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.