Skip to content

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_id picks the template, for example twins, hypothesis or rules_recon. The id is reduced to a base name before any filesystem use.
  • max_iterations bounds the loop. The default is 5.
  • LoopStatus reports progress: WORKING, EXECUTING, OBSERVING, DONE, FAILED or MAX_REACHED.
  • Each turn is TOON: current_thought, has_action, action, action_input, is_final_answer, and on the final turn a nested final_result_json.
  • On DONE, judgements carries 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:

ToolTierWhat it does
read_filereadReads a file from a confined path. Output is truncated.
run_sqlwriteRuns 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_claimsinvokeHands 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): compliance and twins run.
  • A scenario is simulated (SimulateScenario or InteractiveSimulate): twins runs, 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, VisionService and 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, TriageReturnItem and 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=false in FetchAnalysisResult.action_judgements or ExecuteLoopResponse.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.v1 shape (Judgement on Decision and ActionCard). Any verdict key the model writes into its own output is stripped.
  • Configuration. FACE_RALPH_JUDGEMENT controls judging, and FACE_RALPH_JUDGE_MAX_ACTIONS and FACE_RALPH_JUDGE_REVISIONS bound 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:

DecisionWhereRPCWhat’s recorded
Send an option for approvalOptionsHypothesisService.SendToTwinsThe option, its figures as the server computed them, and the approval it needs. Sending decides nothing.
Approve or reject an action cardActionable TwinsTwinsService.ExecuteActiondecision_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 ruleActionable Twins, on an approved cardTwinsService.ProposeStandingRule / ApproveStandingRuleProposer and approver; the approver must be an org admin who is not the proposer.
Address a remediation orderActionable Twins and its remediation viewsComplianceService.AssignRemediationassigned_by and assigned_at_unix
Standing routing ruleThe remediation viewsSetRemediationRouteset_by and set_at_unix
Decide a remediation orderActionable Twins and its remediation viewsDecideRemediationdecided_by and decided_at_unix
Set a rule’s enforcement postureWhy, the rule’s policy drawerRulesService.UpdateRulePolicyThe operator-owned half only. It can’t change findings.
Read actual customer rowsAPI only; the FACE app does not call itConfigService.SampleConnectionDatasetA 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_sql may 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.