Skip to content

Chapter 5 — BlockFlow · AI nodes · Agent node

5.2.6.2 Supervision & Learning — Configuration & Safety

The Agent panel layout, the strict ordering that keeps an unselected decision out of history and execution, the teacher verdict contract, and the metadata that makes MCP tool safety generic.

Agent panel configuration

The panel uses progressive disclosure. Most workflow designers configure the common case with a small set of fields, while detailed controls stay inside advanced accordions. Recommended placement is after Settings and before Input Args.

Supervision & Learning              [ Enable supervision and learning ]

Configuration status
Phase 2 · Student fully gated
Valid configuration · 2 warnings

Operating mode
Lifecycle phase        [ Phase 2 ▼ ]

Model roles
Teacher model          [ profile ▼ ]
Student model          [ profile ▼ ]

Policy profiles
Supervision            [ profile ▼ ]
Trace                  [ profile ▼ ]
Learning-data          [ profile ▼ ]
Deployment             [ profile ▼ ]

Advanced groups
Teacher / Student settings · Review rules · Handover
Tool safety · Trace/privacy · Synthesis · Deployment · Runtime

[ Validate ]   [ Dry-run ]

Profile selectors expose human-readable profile names, immutable versions, model IDs, provider health and capabilities.

Credentials

Raw API keys must never be typed into or serialised from the Agent node. Only server-side credential references are allowed.

Safe decision and handover boundary

Every model round produces one semantic decision: either an external MCP tool call, or a control response such as asking the user a question, presenting a result, requesting confirmation, rerouting, or completing the node. The student output is only a candidate until selection is complete.

Candidate decision
→ deterministic validation
→ review policy decision
→ if review NOT required:  select validated student decision
→ if review IS required:   teacher verdict → validate replacement → select
→ execution / delivery authorization
→ commit ONLY the selected decision to canonical history
→ execute MCP tool OR deliver user/control response
→ record trace / learning event

The ordering is intentionally strict. It prevents a rejected student decision from leaking into normal history, TTS, routing, output parsing or MCP execution.

Teacher verdict contract

The teacher returns a structured operational verdict rather than free-form criticism. This keeps the review machine-readable and prevents the runtime from depending on hidden reasoning text.

{
"verdict": "replace",
"reason_codes": ["wrong_tool"],
"explanation": "Short operational explanation.",
"replacement": {
"decision_type": "tool_call",
"tool_name": "runtime_offered_tool_name",
"arguments": {}
}
}
accept Use the validated student decision.
replace Use the teacher replacement, but only after it passes the same full validation path.
block Do not deliver or execute; follow the configured safe failure behaviour.
escalate Switch to bounded teacher takeover, or route to the configured failure or human handling.

MCP tool execution safety

Tool safety remains generic. Every MCP tool should provide effect metadata in the MCP Registry so that supervision policies can distinguish read operations from protected write or communication actions.

{
"x-openbrain": {
"effect": "read",
"requires_user_confirmation": false,
"idempotency_supported": true,
"sensitive_arguments": ["example_secret_field"]
}
}

Supported effect classes are read , reversible_write , irreversible_write , external_communication and unknown . Missing or unknown effect metadata is treated as protected.

  • Parallel tool calls remain disabled.
  • Tool arguments are validated against the immutable MCP schema offered in that round.
  • Duplicate execution is prevented through execution authorisation and idempotency controls.