AI Worker worker.md

AI Worker Protocol

A worker protocol is a minimal, stable request/response interface that lets you run workers consistently across runtimes and orchestrators.

The goal is not to standardize your entire system. The goal is to make bounded execution portable: invoke, observe, retry safely, and interpret results without bespoke glue code.

Protocols become most useful when paired with design patterns and a clear orchestration layer that routes and validates worker runs.

Key ideas#

  • Requests carry inputs plus constraints and trace context.
  • Responses carry outputs plus status, errors, logs, and artifacts.
  • Status codes should be stable and machine-actionable (retry, fail, or escalate).
  • Artifacts are first-class: files, links, or structured payloads produced during execution.
  • Constraints are part of the protocol: timeouts, token caps, and tool allow-lists.

Diagram#

request: { worker_id, inputs, constraints, trace }
           |
           v
      [ execute ]
           |
           v
response: { status, outputs, error?, logs, artifacts }

Minimal Request/Response Shape#

{
  "worker_id": "code-review-worker",
  "version": "1.0",
  "trace": { "trace_id": "..." },
  "inputs": { "diff": "...", "repo_context": { } },
  "constraints": {
    "timeout_seconds": 60,
    "max_tokens": 1500,
    "tools_allowed": ["read_repo", "static_analysis"]
  }
}
{
  "status": "ok",
  "outputs": {
    "summary": "...",
    "issues": [],
    "risk": "low"
  },
  "observability": {
    "attempt": 1,
    "duration_ms": 8420,
    "log_fields": { "worker_id": "code-review-worker" }
  },
  "artifacts": []
}

Status Taxonomy#

Keep status values small and stable so orchestrators can act without guessing.

  • ok: outputs are valid.
  • retryable_error: transient failure; safe to retry.
  • invalid_request: input schema mismatch; do not retry without changes.
  • invalid_output: output failed validation; retry or fallback based on policy.
  • needs_human: escalation path for approvals or ambiguous cases.

Artifacts and Logs#

Prefer artifacts for large data (files, blobs, long diffs). Return references in the response.

Logs and traces should be structured and consistent: trace_id, worker_id, attempt, duration_ms, status, error_code.

See also#

New to the terminology? See the AI Worker Glossary for definitions of idempotency, retries, orchestration, contracts, and observability.

FAQ#

Do I need a single universal protocol?

No. You need a stable protocol per integration boundary. Start small: a request, a response, and a few observability fields.

Should logs be included in the response?

Often you should emit logs/traces out-of-band, but including a small, structured summary in the response helps debugging and orchestration.

How should failures be represented?

Use a stable status plus a machine-readable error_code (and a human-readable message). Distinguish retryable from non-retryable failures.

If you like minimal interface definitions, you may also find params.md useful.