Agents & oversight
FACE’s agents draft; a person decides. Nothing an agent proposes is sent, filed or paid until a named person approves it on Actionable Twins, and FACE recommends an option only when it is the clear winner on the data.
The agents are prompt templates driven by one orchestrator, the Ralph loop. What an agent may do is bounded in four places:
- the guardrails on its input,
- an authorisation gate on its tools,
- a judging ladder on the actions it proposes,
- a human decision before anything is adopted.
The Ralph orchestrator
RalphOrchestratorService.ExecuteLoop runs a ReAct loop (thought, then action, then
observation) and streams each step back as an ExecuteLoopResponse:
agent_idpicks the template, for exampletwins,hypothesisorrules_recon. The id is reduced to a base name before any filesystem use.max_iterationsbounds the loop. The default is 5.LoopStatusreports progress:WORKING,EXECUTING,OBSERVING,DONE,FAILEDorMAX_REACHED.- Each turn is TOON:
current_thought,has_action,action,action_input,is_final_answer, and on the final turn a nestedfinal_result_json. - On
DONE,judgementscarries the judging ladder’s verdicts.
The same loop drives the scenario simulations behind Options and the interactive
twin (StreamTwins).
Agent templates
The loop serves these agent templates: twins, hypothesis, rules_recon,
ai_posture, compliance, finance, claims, claims_leakage, fraud_detection,
fulfilment, reverse_logistics, route_twin, predictive_maintenance, telemetry,
documentation, vision, voice, cop and self_healing.
Five more templates are refused by the loop on purpose, because they only phrase
figures already computed in Go and must not get the loop’s tools: edge_recon_narrative
(a field-reader walk), and freight_market, counterparty_check,
counterparty_reviews and customer_analysis (the market and due-diligence passes).
Each is guarded where it runs.
Templates are sent to the model verbatim. Nothing renders Jinja. Everything in a template file, including comments, is text the model reads. A template describes the role the model is asked to play. It is not a statement of the platform’s capabilities; for those, read the pages in this section.
Tools
The loop can dispatch three tools. Each passes a fail-closed authorisation gate
(ralphToolGate) that checks the caller’s verified identity against the tool’s tier:
| Tool | Tier | What it does |
|---|---|---|
read_file | read | Reads a file from a confined path. Output is truncated. |
run_sql | write | Runs a query through SqlService.ExecuteSelect, which refuses statements that fail its read-only shape check, against the connection the loop was started with. |
delegate_to_claims | invoke | Hands a sub-task to the claims agent. |
No subject, no tool. A call with no authenticated subject is denied, not skipped. When a tool has no working configuration for the run, the loop tells the model up front and treats the first failure as final.
Agents that run on their own
No one picks an agent and presses Run. The server runs the agents a change makes stale, for the tenant it happened in:
- A rule’s enforcement posture is saved (
RulesService.UpdateRulePolicy, from the policy drawer on Why):complianceandtwinsrun. - A scenario is simulated (
SimulateScenarioorInteractiveSimulate):twinsruns, to turn the outcome into proposals.
A burst of changes becomes one run per agent: each change inside a quiet window pushes
the window out, at most one run per agent is in flight, and a change during a run
queues exactly one follow-up. These runs are named auto:<agent>, and Options
shows the ones in flight in one line (nothing at all when none is running). What they
propose still waits for a person on Actionable Twins.
Guardrails (OpenBias)
Before a prompt reaches the model, an OpenBias judge evaluates it against rule sets from the OpenBias rule sets that ship with the backend:
- A global baseline is prepended to every judge.
- Each service adds its own rules (
TwinsService,ComplianceService,HypothesisService,VisionServiceand others).
The guardrails are wired and checked in three ways:
- The agent lookup fails closed. Every agent id is mapped to its service’s
guardrails. An agent with a template but no mapping is refused with
FailedPrecondition, and the message describes a server configuration defect, not a user error. - Other entry points are guarded too.
GenerateSOP,GenerateRoadmap,TriageReturnItemand camera-feed grading (IngestSurveillanceFeed) each consult the matching judge. - The documents are checked against the code. A parity test compares every rule in the rule documents with what the judges compile. Another test pins which judges are actually consulted.
How the rules change. Rules are versioned, tested against the code before they land, and every refusal is audited.
The judging ladder
Every logistics action a loop’s final answer proposes is judged before it’s
accepted. That covers the twins orchestrator’s decisions and action_cards, other
agents’ recommendations, and the fetch’s Phase 3 twins decision. The judge is the
shared judging ladder library (inference/judgement), the same ladder TIDE’s judge
agent runs. FACE depends on the library, not on TIDE.
- What counts as evidence. The evidence is what the run gathered: its context and its successful tool observations. The claim judged is the action alone, never the orchestrator’s rationale for it.
- Dissent removes the action. When the ladder dissents, the loop may be sent back
to revise. An action still dissented from is removed. It survives only as
accepted=falseinFetchAnalysisResult.action_judgementsorExecuteLoopResponse.judgements. - Unable-to-judge is never concurrence. An action that was not judged is kept as unable-to-judge, never as accepted.
- Verdicts can’t be forged by the model. Verdicts travel out of band in the shared
runink.ui.judgement.v1shape (JudgementonDecisionandActionCard). Any verdict key the model writes into its own output is stripped. - Configuration.
FACE_RALPH_JUDGEMENTcontrols judging, andFACE_RALPH_JUDGE_MAX_ACTIONSandFACE_RALPH_JUDGE_REVISIONSbound its cost.
The fast path
In front of the model-based judge sits a pinned tree model from ml/decide, running
through judgefast. It’s controlled by FACE_FAST_JUDGEMENT, which is on by default.
- It answers only at the ladder’s final gate, and the deterministic gates run first.
- It never answers with no evidence.
- It leaves sensitive domains to the model-based judge.
- It abstains on anything it can’t answer, and that goes to the model exactly as before.
Each model-based verdict records which model judged it in judged_by: either the
fast model with its full sha256 digest, or llm.
Human-in-the-loop points
A person makes these decisions. The server records who made each one, from the verified session:
| Decision | Where | RPC | What’s recorded |
|---|---|---|---|
| Send an option for approval | Options | HypothesisService.SendToTwins | The option, its figures as the server computed them, and the approval it needs. Sending decides nothing. |
| Approve or reject an action card | Actionable Twins | TwinsService.ExecuteAction | decision_trail. A reason is required on rejection. Approval seals the evidence document. A two-person card needs two different named people. |
| Make an approved decision a standing rule | Actionable Twins, on an approved card | TwinsService.ProposeStandingRule / ApproveStandingRule | Proposer and approver; the approver must be an org admin who is not the proposer. |
| Address a remediation order | Actionable Twins and its remediation views | ComplianceService.AssignRemediation | assigned_by and assigned_at_unix |
| Standing routing rule | The remediation views | SetRemediationRoute | set_by and set_at_unix |
| Decide a remediation order | Actionable Twins and its remediation views | DecideRemediation | decided_by and decided_at_unix |
| Set a rule’s enforcement posture | Why, the rule’s policy drawer | RulesService.UpdateRulePolicy | The operator-owned half only. It can’t change findings. |
| Read actual customer rows | API only; the FACE app does not call it | ConfigService.SampleConnectionDataset | A separate, bounded call. Exploring a source never samples it. See Data sources. |
Nothing FACE derives is sent, filed or settled without one of these decisions. Where an
action does execute, for example an email draft through a connected account, its
outcome is reported per artifact in not_executed. See
Action cards & money.
Reading the results
- Guardrails make misuse harder; they don’t make it impossible. A prompt fence makes injection harder, and it does not solve it.
- Judging is a second opinion. A concurring verdict means the judge found the action supported by the evidence the run gathered. It doesn’t show the action is right.
- The tool gate authorises the tool, not the arguments. A caller permitted to use
run_sqlmay still see the model choose a query they would not have written. Tenant scoping and the read-only shape check bound what that query can reach. - Recording a human decision is not enforcing it. The recorded decision shows who approved what. It doesn’t show that they reviewed it carefully.