Forge Platform

Handbook

Forge Agent

A Forge Agent is any bounded, governable agent session that participates in a ForgeRun. Each session is recorded as an AgentRun (arun_*) with a workcell identifier, a governance mode, and a WorkcellResult returned into…

Definition

A Forge Agent is any bounded, governable agent session that participates in a ForgeRun. Each session is recorded as an AgentRun (arun_*) with a workcell identifier, a governance mode, and a WorkcellResult returned into the run spine.

Forge is not an agent. Forge is the operating envelope that makes many agents governable. See Platform charter.

What a Forge Agent is not

Misuse Correct framing
“The Forge platform” Forge = control plane + contracts
Ungoverned Cursor chat Outside a ForgeRun unless wrapped as an AgentRun
Marketing or growth “campaign” bot Not a Forge Agent; see Forge Campaign for automation campaigns

Schema mapping

Concept Schema Identifier
Run container forge.run.v1 frun_*
Agent session forge.agent_run.v1 arun_*
Input envelope forge.workcell_request.v1 per request
Output envelope forge.workcell_result.v1 per workcell completion

Samples: schemas/agent_run.v1.schema.json, sprints/selfhost-alpha/samples/agent_run.json.

Workcell identifiers

Prefer a concrete workcell id over the generic phrase “forge-agent.”

Workcell id Role Typical mode Responsibility
hermes operator operator / proposal Adaptive operator, memory, MCP
factory implementation_worker sandboxed_implementation Coding and review patches
openclaw channel_gateway readonly / proposal Chat ingress and status relay
local_runner operator operator Self-Host Alpha bounded repo checks
campaign_orchestrator operator operator Forge Campaign: branch, Fleet submit/watch, integrate, PR stack
fleet_ux_worker implementation_worker sandboxed_implementation In-container UX audit/remediation (Fleet job)
cursor_cli implementation_worker sandboxed_implementation Headless Cursor CLI agent steps inside a campaign
local_llm_worker reviewer proposal Single-rule UX micro-agent via LCDL; runner in forge-workcells; pack in KS

Extend the table in Workcell catalog when adding workcells.

Micro-agent (local LLM)

The local_llm_worker workcell implements Forge micro-agent runs: WorkcellRequest-shaped inputs (pack path, context.json, out dir) and JSON findings compatible with the KS harness parser. It does not replace Cursor for general IDE work.

Governance modes

AgentRuns align with ForgeRun governance.approval_mode and WorkcellRequest mode:

  • readonly — inspect and report only
  • proposal — suggest changes; human approves before apply
  • operator — coordinate tools and runs within policy
  • sandboxed_implementation — bounded edit/execute inside approved boundaries (e.g. Fleet workspace, local runner allowlist)

See Governed workflows and rules for approval gates.

Product boundaries

Concern Owner
Run state, approvals, evidence review Lenses
Container execution, job logs Fleet
Governed LLM contracts and traces LCDL
Process policy and Versonas Blueprints
Agent session record and workcell I/O Forge Platform schemas + Lenses projection

Fleet runs docker_argv jobs; it does not replace AgentRun semantics. The campaign orchestrator workcell calls Fleet APIs; the fleet_ux_worker workcell runs inside the container and reports via Fleet workspace_worker_* bridge.

Anti-patterns

  • Letting any workcell write final ForgeRun decision state without Lenses review.
  • Treating Hermes as mandatory for governance (platform must work with Hermes disabled).
  • Giving agents raw Fleet power without templates or campaign policy.
  • Using “forge-agent” in user-facing copy when a specific workcell or product name is clearer.