Agent orchestrator

RalphOrchestratorService runs one of FACE’s agents as a ReAct loop (thought, action, observation) on the sovereign model plane and streams every step to the caller. The final answer carries the platform’s judgement on each action the agent proposed. The cockpit’s twins view and orchestrator console use this service.

Summary

RalphOrchestratorService

Full name semantics.v1.RalphOrchestratorService.

ExecuteLoop

rpc ExecuteLoop(ExecuteLoopRequest) returns (stream ExecuteLoopResponse);

• Kind: Server streaming. Available over native gRPC and gRPC-web.
• Auth: Bearer session. Which tools the agent may use depends on the caller’s role. See Tool gate.
• Errors: FAILED_PRECONDITION if agent_id names an agent that this build does not serve through the loop. The stream also ends with an error, without a gRPC status code of its own (clients see UNKNOWN), in these cases:
  • user_command trips the prompt-injection check;
  • the command violates the agent’s guardrail rules;
  • no template exists for agent_id;
  • a resumed thread cannot be loaded;
  • the model plane fails mid-run. A LOOP_STATUS_FAILED message is sent first.

The server builds the opening prompt from context_payload and user_command, then runs up to max_iterations model turns. Each turn streams one or more messages:

1. LOOP_STATUS_WORKING: the model is producing a thought. current_thought is set.
2. LOOP_STATUS_EXECUTING: the agent chose a tool. action_attempted is set.
3. LOOP_STATUS_OBSERVING: the tool answered. observation_result carries its output.

The stream ends with exactly one terminal message:

When judgement is enabled and a proposed action is dissented, the agent may revise its answer. A revision runs within the same max_iterations budget, and the next final answer has a higher Judgement.round.

Resuming. When thread_id is set, the run is recorded under that id and can be resumed: calling ExecuteLoop again with the same thread_id continues from the recorded steps. If that thread had already reached a final answer, the stream returns a single LOOP_STATUS_DONE message with the recorded answer, without running the model again. The thread id also identifies the run in ActivityService.

Tool gate

The agent chooses tools, but the server checks each tool call against the caller’s role before running it:

Service-account sessions count as Readers for tool access. A refused tool call does not fail the RPC. The refusal comes back to the agent as the tool’s observation (an error object in observation_result), and the loop continues. The gate authorises the tool, not its arguments.

• run_sql runs against the connection named by parameters["connection_id"]. It is marked unavailable to the agent when no connection is given. Results returned to the agent are capped at 4 KB. See SQL for the read-only rules.
• read_file is limited to the agent’s permitted location. Results are truncated at 2 KB.
• delegate_to_claims hands a sub-task to the claims agent.

An unknown tool name returns a “not registered” observation.

Request: ExecuteLoopRequest

Response: ExecuteLoopResponse

One message per step. Fields that do not apply to a step are empty.

Agents

agent_id must be one of the agents this build serves through the loop. Each one is checked against its own guardrail rule set:

To see what a rule set checks before sending a command, use MetasearchService/ListBiasRules and EvaluateBias with the rule-set name.

Messages

ImagePart

Defined in face.proto.

Enums

LoopStatus