AI Worker worker.md

Code Review Worker

Problem: Review a PR diff and return actionable feedback with a coarse risk rating.

This example follows the core principles described in the AI Worker Design Patterns and uses the standard Worker Protocol schema.

Key ideas#

  • Keep the worker single-purpose and explicit about inputs and outputs.
  • Put hard limits in the contract (timeout, retries, tools allowed).
  • Make failures machine-actionable with stable error codes.
  • Emit structured signals so orchestrators can route, retry, or escalate.

Diagram#

diff + context -> worker -> issues + risk

Worker spec#

worker_id: code-review-worker
version: 1.0
purpose: Review a PR diff and return actionable feedback with a coarse risk rating.
inputs:
  - diff: string
  - repo_context: object
  - guidelines: array (optional)
outputs:
  - summary: string
  - issues: array
  - risk: enum(low, medium, high)
constraints:
  timeout_seconds: 60
  max_tokens: 1500
  tools_allowed: [read_repo, static_analysis]
retries:
  max_attempts: 2
  backoff: exponential
observability:
  trace_id: required
  log_fields: [worker_id, attempt, duration_ms]

Input schema#

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "diff": {
      "type": "string"
    },
    "repo_context": {
      "type": "object"
    },
    "guidelines": {
      "type": "array"
    }
  },
  "required": [
    "diff",
    "repo_context"
  ]
}

Output schema#

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "summary": {
      "type": "string"
    },
    "issues": {
      "type": "array"
    },
    "risk": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    }
  }
}

Constraints#

{
  "timeout_seconds": 60,
  "max_tokens": 1500,
  "retries": {
    "max_attempts": 2,
    "backoff": "exponential"
  },
  "rate_limit": "per-tenant (example: 10/min)",
  "tools_allowed": [
    "read_repo",
    "static_analysis"
  ]
}

Failure modes & handling#

  • Diff is incomplete: return error_code=missing_diff_context.
  • Static analysis tool fails: proceed with model-only review and set warnings[].
  • Too many issues: return top-N with a stable truncation field (e.g., issues_truncated=true).

Observability signals#

  • logs: worker_id, attempt, duration_ms, status, error_code
  • metrics: success_count, failure_count, retry_count, p95_duration_ms
  • trace fields: trace_id, span_id, upstream_request_id (if present)

See also#

FAQ#

Should the worker return partial results on failure?

If partial results are safe and useful, return them with a stable status and error_code. Otherwise fail fast and let orchestration decide.

Where should large artifacts go?

Store them externally (object storage or DB) and return a reference (URL or artifact ID) in the response.

How should I choose timeouts?

Set a hard ceiling based on SLOs and queue backpressure. Prefer smaller workers with tighter timeouts over monolith workers.