YOU

Agent worker

Configure an AGENT_WORKER for agent-loop execution: model and provider identity, agentTools policy, permissions, resources, and AGENT_RUN workstation companionship.

How To Use

Author a worker with type AGENT_WORKER. Put model and modelProvider on the worker when you need authored identity; authored values always win over operator defaults. Keep the shared system prompt in body. Configure agentTools.policy when the loop needs filesystem tools. Bind the worker from an AGENT_RUN workstation. Runner selection is separate from modelProvider—choose the built-in runner through factory or workstation runner fields. Agent workers are not INFERENCE_WORKER backends: they do not declare operations, and validation rejects capability declarations on AGENT_WORKER.

Discriminator: type = AGENT_WORKER

AGENT_WORKER requires an AGENT_RUN workstation companion. The workstation binds the worker name and owns step routing, prompts, limits, and outputs.

Schema reference

The embed below shows the live Worker base definition with AGENT_WORKER overlay applicability. Selected fields are agent-loop exclusive. Excluded fields belong to other WorkerType families and must not appear on this variant. Open the full Factory schema reference for exhaustive field lookup rather than copying contract text into this page.

Worker

object

A reusable worker definition that tells the factory how a workstation should execute work, such as through a model-backed agent or a script.

  • additionalPropertiesfalse (closed)

Fields

  • agentToolsagentToolsOptionalAgentWorkerToolsConfigSelected

    Explicit agent-loop tool policy for AGENT_WORKER definitions. Omit or set policy DISABLED to run agent loops without advertising or executing tools.

  • argsargsOptionalarrayExcluded

    Additional command arguments passed to the configured command.

  • authauthOptionalHostedWorkerAuthExcluded

    Hosted-worker authentication contract. V1 hosted workers accept only auth.secretRef.

  • bodybodyOptionalstring

    Inline worker instructions or script body when the worker is authored directly in factory config.

  • commandcommandOptionalstringExcluded

    Command to execute when this worker runs through a command or script provider.

  • descriptiondescriptionOptionalNameValue

    Optional localized customer-facing explanation of this worker.

  • executorProviderexecutorProviderOptionalWorkerProviderExcluded

    Execution mechanism. Use `ACP` for ACP-backed workers and put the configured integration identity (for example `cursor-acp`) in modelProvider. `SCRIPT_WRAP` remains the command-wrapper compatibility value; legacy named executor identities remain accepted during migration.

  • ididOptionalstring

    Optional durable public identifier for this worker. When present, graph and layout references should use this id instead of the mutable name.

  • linearlinearOptionalHostedLinearWorkerConfigExcluded

    Provider-specific configuration for the built-in hosted LINEAR worker.

  • modelmodelOptionalstring

    Model identifier to request from the configured model provider when this worker uses model execution.

  • modelLocalitymodelLocalityOptionalWorkerModelLocalityExcluded

    Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution.

  • modelProvidermodelProviderOptionaloneOf

    Canonical provider identity used for model routing and provider diagnostics, or an exact invocation-parameter placeholder such as `${modelProvider}`. For `executorProvider: ACP`, this names the configured ACP integration, such as `cursor-acp`. Extension identities use lowercase standardized syntax; built-in values such as `CLAUDE` and `CODEX` remain compatibility conveniences.

  • namenameRequiredstring

    Worker name referenced by Workstation.worker.

  • operationsoperationsOptionalModelOperation[]Excluded

    Provider-agnostic model operations that this worker can execute, including named input and output slots.

  • providerproviderOptionalHostedWorkerProviderExcluded

    Built-in hosted provider identity when this worker uses repository-owned hosted execution.

  • reasoningEffortreasoningEffortOptionalReasoningEffort
  • resourcesresourcesOptionalResourceRequirement[]

    Resource capacity this worker requires before it can be dispatched.

  • skipPermissionsskipPermissionsOptionalbooleanSelected

    When true, bypasses permission checks for providers that support permission gating.

  • stopTokenstopTokenOptionalstring

    Marker that tells model-oriented workers where to stop generated output when the provider supports it.

  • timeouttimeoutOptionalstring

    Optional Go duration that caps one worker execution attempt.

  • typetypeOptionalWorkerType

    Worker implementation family to instantiate for this definition.

Examples

Use the minimal valid example when starting an AGENT_WORKER. The misuse example shows operations on an agent worker—operations belong on INFERENCE_WORKER and fail validation on AGENT_WORKER.

Minimal valid AGENT_WORKER:

{
  "name": "agent-main",
  "type": "AGENT_WORKER",
  "model": "gpt-5-codex",
  "modelProvider": "CODEX",
  "body": "You are a software engineer. Follow the workstation instructions and keep changes scoped to the current work item.",
  "agentTools": {
    "policy": "DISABLED"
  }
}

Incompatible misuse — operations on AGENT_WORKER (rejected):

{
  "name": "agent-main",
  "type": "AGENT_WORKER",
  "model": "gpt-5-codex",
  "modelProvider": "CODEX",
  "operations": [
    "CHAT"
  ],
  "body": "You are a software engineer."
}

operations is an inference capability field. Validation rejects it on AGENT_WORKER. Use INFERENCE_WORKER for one-shot operations.

On this page

How To UseSchema referenceExamples