Configuration

Configure you-agent-factory with factory.json topology: work types, workers, workstations, resources, and how the pieces fit.

What Lives Where

Put topology in factory.json. Keep worker runtime instructions in workers/<name>/AGENTS.md and workstation runtime instructions in workstations/<name>/AGENTS.md. Drop watched single-work-type requests under inputs/<work-type>/default/, and mixed or relation-heavy batch files under inputs/BATCH/default/. The recommended factory directory layout looks like this:

factory/
  factory.json
  workers/
    processor/AGENTS.md
  workstations/
    process/AGENTS.md
  inputs/
    task/default/request.json

Inline runtime fields in factory.json still work for portable single-file configs, but the split layout is the recommended authoring path. Live saves persist the split layout: a thin factory.json plus workers/, workstations/, and default inputs/ channels when definitions exist.

How The Pieces Fit

Work enters the factory as a token in a work type's initial state. A workstation is enabled when its configured input places have matching tokens. The workstation dispatches to its worker, then routes the token based on the worker outcome:

Worker outcome	Routing field
Accepted	outputs
Continue	onContinue
Rejected	onRejection
Failed, timed out, or errored	onFailure

Each workType and state pair becomes a place named <workType>:<state>, such as task:init. That place naming is how workstation inputs and outputs connect to the work-type lifecycle.

Factory Root Properties

The live Factory schema root lists the topology fields factory.json can declare. Required fields define executable workflow. Optional resources bound concurrency. Identity and runner fields set factory-level defaults. layout and supportingFiles are non-executable portability metadata — they do not change runtime topology. Open the full Factory schema and API references when you need exhaustive contract lookup beyond this root summary.

You Factory configuration

object

Top-level factory.json contract. Declare the work types, resources, portability resources, workers, and workstations that make up one authored factory here. Guarded loop breakers should be authored as guarded LOGICAL_MOVE workstations using VISIT_COUNT guards instead of a top-level exhaustion-rules field.

additionalPropertiesfalse (closed)

Fields

descriptiondescriptionOptionalNameValue
Optional localized customer-facing explanation of this Factory.
examplesexamplesOptionalFactoryInvocationExample[]
Ordered runnable invocation examples. Canonical Factory documents write examples here; legacy invocationSignature.examples are accepted only by the Factory input compatibility mapper.
factoryDirectoryfactoryDirectoryOptionalstring
Directory that contained the factory.json used for this serialized runtime config.
guardsguardsOptionalFactoryGuard[]
Root-level guards that apply across the factory instead of one specific workstation or input.
ididOptionalstring
Factory identifier used as the factory-level template context fallback.
inputTypesinputTypesOptionalInputType[]
Named input kinds accepted by the factory. The default input type is implicit and must not be declared.
invocationReturninvocationReturnOptionalInvocationReturn
Optional factory-authored invocation primary-result policy shared by CLI and API entrypoints. When omitted, runtimes use the SUBMITTED_WORK_TERMINAL fallback and return the first terminal content for the work item originally submitted by the invocation.
invocationSignatureinvocationSignatureOptionalFactoryInvocationSignature
Optional canonical callable argument contract shared by CLI, API, dashboard, docs, and packaged factories. When omitted, callers use the factory's compatibility invocation behavior.
layoutlayoutOptionalFactoryLayout
Optional non-executable graph editor layout metadata keyed by canonical graph node and edge ids.
metadatametadataOptionalStringMap
Free-form factory-level metadata carried through runtime serialization and replay diagnostics.
namenameRequiredFactoryName
orchestratororchestratorOptionalFactoryOrchestrator
Authored orchestrator identity for this factory. When omitted, existing Petri factories load through compatibility defaulting to orchestrator.kind = PETRI.
resourcesresourcesOptionalResource[]
Shared capacity pools that workers or workstations can consume while work is executing.
runnerrunnerOptionalRunnerID
Default runner selection for the factory when a workstation does not declare its own runner override.
sourceDirectorysourceDirectoryOptionalstring
Original source directory for record/replay and drift diagnostics.
supportingFilessupportingFilesOptionalResourceManifest
Optional portability manifest for validation-only external tools and portable bundled files. During v1 factory sharing, bundled INPUT files represent a share-time snapshot of the source factory's current inputs work so recipients restore detached starter-work copies that no longer sync back to the original factory. This contract is distinct from runtime-capacity resources.
versionversionOptionalHybridLogicalTimestamp
Server-managed current-factory version metadata. Clients should echo this value on complete replacement saves when they want stale-write detection, but durable factory configuration does not treat it as customer-authored topology.
workTypesworkTypesOptionalWorkType[]
Customer-authored work item categories and the lifecycle states each one can occupy.
workersworkersOptionalWorker[]
Reusable worker definitions that workstations reference by name when dispatching work.
workstationsworkstationsOptionalWorkstation[]
Processing steps that consume work, invoke workers, and emit the next work states.

Runtime topology is workTypes, workers, workstations, and optional resources. layout and supportingFiles travel with the factory for portability and presentation only. Do not treat them as executable workflow fields.

Minimal Factory

A minimal factory needs one work type, one worker, and one workstation that moves submitted work from an initial state to a terminal state. Copy this shape, then add matching workers/processor/AGENTS.md and workstations/process/AGENTS.md files:

{
  "workTypes": [
    {
      "name": "task",
      "states": [
        { "name": "init", "type": "INITIAL" },
        { "name": "complete", "type": "TERMINAL" },
        { "name": "failed", "type": "FAILED" }
      ]
    }
  ],
  "workers": [
    { "name": "processor" }
  ],
  "workstations": [
    {
      "name": "process",
      "worker": "processor",
      "inputs": [{ "workType": "task", "state": "init" }],
      "outputs": [{ "workType": "task", "state": "complete" }],
      "onFailure": { "workType": "task", "state": "failed" }
    }
  ]
}

Accepted work moves through outputs to task:complete. Failures route through onFailure to task:failed. Add onContinue or onRejection only when those outcomes are part of the workstation contract.

How To Use

Start from factory.json as the topology root, then add split worker and workstation instruction files named to match the entries in that file. Use this page for the layout, live root-property summary, and minimal factory shape. This overview stays at topology depth. Open the child documentation pages below when you need the deep contracts those pieces own: workers, workstations, and resources.

Limits And Assumptions

This page is a web topology overview for factory.json. It is not a sync of packaged CLI docs, not the operator model-defaults deep dive in ~/.you-agent-factory/config.json, and not the submitting-work, batch, relationships, or harness-support references. Deep worker-type, workstation-kind, and resource-pool field contracts belong on the workers, workstations, and resources documentation pages — this overview does not absorb those contracts. Exhaustive Factory field and operation inventories live on the schema and API reference pages linked from the root-properties section.