Multi-Agent Contracts : Biligent#5

Overview of Biligent

Protocol Spec Section 5: Contracts Inter-Agent Protocols 12 min read

Biligent Multi-Agent Contracts: Interaction Envelopes, Collaboration Flows & Permission Matrix (DP-05)

How autonomous specialist agents coordinate in harmony: Standardized contract envelopes, asynchronous event pairs, resilient single-query orchestration, and strict RBAC permission matrices.

🐾 The Kalahari Sentinel & The Specialists: In the wild, a meerkat mob succeeds through immaculate role coordination—a dedicated sentinel monitors the horizon while specialized companions dig, forage, and communicate through swift signals. The Biligent architecture mirrors this exact harmony through strict contract envelopes and event-driven collaboration.

Table of Contents

• 5-1. Request, Result, and Event Envelopes & Core Rules
• 5-2. Contract Request & Event Pairing Matrix
• 5-3. Step-by-Step Query Collaboration Lifecycle
• 5-4. Collaboration Principles, Invocation Patterns & Invariants
• 5-5. Access Control & Permission Matrix (권한 표)

5-1 Request, Result, and Event Envelopes & Core Rules

The formal schemas for all cross-boundary messages reside canonically within contracts (defined in Round 0). All inter-agent data exchanges must be packed inside strictly versioned envelopes.

Envelope Format	Field Schema & Structure
Agent Request Envelope	request_id · request_type · format_version · domain_id · requester{internal_user_id, session_id} · trace_id · thread_id (optional) · cause_ref · request_payload · deadline
Agent Result Envelope	request_id · result_status (ok | partial | needs_user | failed) · result_payload · evidence_list · user_notes_list · failed_units_list · reason · trace_id

📌 5 Fundamental Communication Invariants

1. Domain Isolation: domain_id is mandatory on every envelope. Agents are strictly confined to invoking module functions bound to that specific domain.
2. Unified User Egress: In question-answering workflows, ONLY A0 (Dialogue Specialist) emits final answers to the user. A7 (Semantic Deliberation Question) and A8 (Exploratory Question) communicate exclusively via asynchronous events. Support agents return structured Result Envelopes only.
3. Canonical Schema Placement: Content schemas for each distinct request type are formally declared in contracts.
4. Pending Choice Escalation: Whenever an agent receives needs_user, A0 constructs a pending user selection (conversation.create_pending_choice).
5. Deadline Timeout Handling: If an agent exceeds its assigned deadline (deadline), A0 degrades gracefully and treats the outcome as partial.

5-2 Contract Request & Event Pairing Matrix

The comprehensive interaction pairs across rounds. The Connecting Round denotes when both sender and receiver exist, establishing the integration test milestone.

Type	Interaction Name	Sender (Round)	Receiver (Round)	Connecting Round
Contract Request	Execute Query (질의 실행)	ui (R0), A4 (R11), A8 (R12)	A0 (R1)	R1 · R11 · R12
	Interpret Query (질의 해석)	A0 (R5)	A1 (R5)	R5
	Start Investigation (조사 시작)	ui (R7)	A5 (R7)	R7
	Run Evaluation (평가 실행)	ui (R11)	A4 (R11)	R11
	Execute Schedule (일정 실행)	Platform Top (R0)	A4 (R11), A8 (R12)	R11 · R12
	Re-analyze Data (재분석)	A5 (R7)	A6 (R3)	R7
	Candidate Deliberation (후보 협의)	A5 (R7)	A7 (R4)	R7
	meaning_opinion	A0 (R6)	A7 (R4)	R6
	structure_edit / confirm	ui (R4)	A6 (R3)	R4
	structure_edit (Answer Screen)	A0 (R6)	A6 (R3)	R6
	apply_node_batch	ui (R4)	A7 (R4)	R4
	precheck_opinion / node_detail	ui (R4)	A7 (R4)	R4
	resolve_meaning_conflict	ui (R4)	A7 (R4)	R4
	revert_knowledge	ui (R4)	A6 (R3), A7 (R4)	R4
Asynchronous Event	Upload Complete (업로드 완료)	ingest.loader (R1)	A6 (R3)	R3
	User Document Registered	user_input (R3)	A6 (R3), A7 (R4)	R3 · R4
	Connectivity Built (연결도 완성)	A6 (R3)	A7 (R4)	R4
	data_updated	A6 (R3)	derived_data (R5), conversation (R6), A4 (R11), A5 (R7)	R5 · R6 · R7 · R11
	meaning_changed	A7 (R4)	derived_data (R5), conversation (R6), retrieval (R6), quality_metrics (R11)	R5 · R6 · R11
	structure_changed	A6 (R3)	A7 (R4), derived_data (R5), conversation (R6), quality_metrics (R11)	R4 · R5 · R6 · R11
	node_state_changed	A7 (R4)	derived_data (R5), conversation (R6)	R5 · R6
	meaning_conflict	A6 (R3), A7 (R4)	ui (R4)	R4
	confirmed_reuse	A6 (R9)	derived_data (R5), conversation (R6), quality_metrics (R11)	R9 · R11
	carryover_choice_needed	domain_lifecycle (R9)	ui (R0)	R9
	carryover_ready	domain_lifecycle (R9)	A6 (R9)	R9
	Semantic Deliberation Question	A7 (R4)	ui (R4), quality_metrics (R11)	R4 · R11
	Present Exploratory Question	A8 (R12)	ui (R0), quality_metrics (R11)	R12
	Knowledge Changed (지식 변경)	knowledge_policy (R4)	derived_data (R5), conversation (R6), retrieval (R6), A4 (R11), A8 (R12)	R5 · R6 · R11 · R12
	Repeated Rejection Signal	quality_metrics (R11)	A7 (R4, if semantic cause), A5 (R7, other causes)	R11
	Demand Accumulated (수요 누적)	pipeline_runner (R7)	A5 (R7)	R7
	Domain Registered (도메인 등록)	domain_lifecycle (R0)	A5 (R7)	R7
	Progress Heartbeat (진행)	observability (R0)	ui (R0)	R0

5-3 Step-by-Step Query Collaboration Lifecycle

When a user enters a query, the orchestrator A0 harmonizes retrieval, interpretation, calculation, safety guards, and evidence synthesis through a predictable, resilient lifecycle.

1. Ingress & Authorization (User → A0)

User submits Query + Thread ID. A0 validates user permissions via access.authorize and loads conversational state via conversation.

2. Concept Search & Ambiguity Resolution (A0 → retrieval)

A0 queries retrieval for domain concepts.
• No Candidates: Emits what is known/unknown; logs demand if learning signal enabled.
• Tied / Ambiguous: Presents interactive choices to user, creates a pending choice token, and pauses for user selection.
• Confirmed: Evaluates usable knowledge tier (knowledge_policy.usable) and proceeds.

3. Query Interpretation & Plan Synthesis (A0 → A1)

A0 requests slot extraction and calculation planning from A1.
• If condition slot is ambiguous (needs_user), A0 prompts user for clarification with options.
• If valid (ok), returns verified slots and execution plan (CalcPlan).

4. Deterministic Calculation (A0 → calc_runner)

A0 delegates plan execution to calc_runner.run_plan. Zero LLM calls are made during mathematical calculations, grouping, segmentation, or data lineage extraction.

5. Explanation Synthesis & Guard Validation (A0 → guard)

A0 drafts the natural language narrative and submits it to guard.
• If factual claims mismatch computed values: Retries generation or defaults to a safe deterministic template.
• If passed: Proceeds to evidence assembly.

6. Evidence Assembly & Delivery (A0 → User)

A0 builds evidence panels, records full turn context into conversation, and transmits the verified answer with step reasons, calculation plan badges, and drill-down evidence.

💡 Span Tracking: Every user request opens a dedicated OpenTelemetry trace span. Span lifecycles (start/finish) automatically emit progress heartbeat events to the UI.

5-4 Collaboration Principles, Invocation Patterns & Invariants

Dimension	Architectural Specification
Orchestrator Role	A0 is the exclusive orchestrator of the QA collaboration pipeline. All inter-agent requests follow contract request/event protocols.
Invocation Patterns	A0 ↔ A1: In-process synchronous invocation. A4 / A5: Asynchronous execution mediated by task records and single-execution distributed locks (store.lock).
Deduplication	Concurrent A4/A5 triggers on the same domain/target run only once under lock; duplicate triggers are recorded and bypassed.
State Isolation	Agents never read each other's private state, strictly respecting boundary invariants.
Discrepancy Resolution	When support agent outputs conflict, A0 resolves using deterministic rule logic and exposes the rationale in evidence—never delegating resolution to non-deterministic LLMs.
Graceful Degradation	If any support agent fails or times out, A0 returns a partial response (partial) or pending hold rather than failing completely.

⚖️ The 4 Core Architectural Invariants

1. Deterministic Value Calculations: All value computations are strictly performed by components (calc_runner, algorithms).
2. Human Gate Safeguards: A5 (Investigation Coordinator) halts unconditionally before any human review gate.
3. Domain Isolation on Storage: All persistence operations must strictly respect domain partitioning.
4. Knowledge Tier Transparency: Operational answers must visibly indicate the verification tier of all referenced knowledge items.

5-5 Access Control & Permission Matrix (권한 표)

Authorization across Biligent is governed declaratively by a single canonical Permission Matrix. Evaluated solely by access.authorize.

Allowed + Learn (허용·학습) Allowed Only (허용) Denied (불허) — (Out of Tier Scope)

Operation Type	Server Admin	Domain Admin	Read + Learn	Read-Only	Invoking Module / Agent
Register Account (계정 등록)	Allowed	—	—	—	access.register_account
Assign Server Admin	Allowed	—	—	—	access.set_server_admin
Create Domain (도메인 생성)	Allowed	—	—	—	domain_lifecycle.create
Assign First Domain Admin	Allowed	—	—	—	access.assign_role
Adopt Global Assets (Prompt / Code)	Allowed	—	—	—	eval_lab.activate, codegen.adopt
Import Server Bundle (서버 간 가져오기)	Allowed	—	—	—	domain_lifecycle.import_bundle
Querying (질문 / 응답 / 재현)	—	Allow+Learn	Allow+Learn	Allowed	A0 Query Execution
View Answers (답변 보기)	—	Allowed	Allowed	Allowed	ui Chat Panel
View Evidence Panel (근거창 보기)	—	Allowed	Allowed	Denied	evidence_view
Submit Feedback & Row Inclusion	—	Allow+Learn	Allow+Learn	Denied	A0 Opinion Eval, feedback.submit
Confirm Evidence Row (근거 행 확인)	—	Allow+Learn	Allow+Learn	Denied	knowledge_policy.record_confirmation
Node Opinion / State / Distinction Change	—	Allow+Learn	Allow+Learn	Denied	user_input, A6, A7
Structure Edit (구조 수정)	—	Allow+Learn	Allow+Learn	Denied	user_input.record_structure_edit, A6
Trigger Investigation / Evaluation	—	Allow+Learn	Allow+Learn	Denied	A5 Investigation, A4 Evaluation
Approve / Confirm / Reject Knowledge	—	Allow+Learn	Allow+Learn	Denied	knowledge_policy.transition
Confirm Question Set (평가세트 확정)	—	Allow+Learn	Allow+Learn	Denied	eval_lab.confirm_question_set
Resolve Semantic Conflict (의미 충돌 결정)	—	Allowed	Denied	Denied	A7 resolve_meaning_conflict
Assign Roles & Allowed Data Types	—	Allowed	Denied	Denied	access.assign_role, set_allowed_types
Reset / Export Domain (초기화 / 내보내기)	—	Allowed	Denied	Denied	domain_lifecycle.reset / export
Set LLM Spending & Egress Policy	—	Allowed	Denied	Denied	llm_policy.set_cost_policy
Select Carryover Source (이월 원천 선택)	—	Allowed	Denied	Denied	domain_lifecycle.choose_carryover

🛡️ Permission Enforcement Principles

• Learning Signal Gating: Actions without Allowed + Learn do NOT contribute to knowledge base updates, demand tracking, personalization know-how, or system metrics. Their clarifications stay purely isolated to their active conversational turn.
• Caller-Side Responsibility: Logging points (feedback.submit, knowledge_policy.record_confirmation, etc.) do not re-check permissions. The caller (A0 or UI Shell) gates logging based on the authorization payload.
• UI Element Omission: Operations flagged as Denied are omitted entirely from the UI DOM, preventing unauthorized interaction attempts.
• Open Registration Extensibility: New operations can be seamlessly introduced into the open operation list without breaking legacy permission schemas.

#MultiAgentCollaboration #ContractProtocols #AccessControlMatrix #Biligent #SoftwareArchitecture

© Biligent Multi-Agent Specification Series. All rights reserved.