Two-Layer Multi-Agent & Package Foundation Design : Biligent#4

Overview of Biligent

Architecture Spec Section 4: Module Structure Multi-Agent Systems 15 min read

Biligent System Architecture: Two-Layer Multi-Agent & Package Foundation Design 

A comprehensive deep-dive into the architectural blueprint of the Biligent engine—featuring clean decoupling between autonomous runtime agents and deterministic, reusable package layers.

🦉 The Sentinel & The Specialists: Much like an alert Eurasian Eagle Owl overseeing its domain with precise vision and calculated judgment, the Biligent architecture pairs a vigilant conversational orchestrator (A0) with sharp, specialized autonomous agents to govern complex data semantics.

Table of Contents

• 4-1. Two-Layer Structure and Unit Boundary Rules
• 4-2. System Layer Hierarchy Diagram
• 4-3. Agent Layer Specifications (A0 ~ A8)
• 4-4. Package Layer (33 Modules across 9 Intermediate Groups)
• 4-6. Dependency Rules & Interaction Paradigms
• 4-7. Major, Mid, and Subgroup Taxonomy
• 4-8. Dual Constants Architecture
• 4-9. Independence Principles & Verification Checks

4-1 Two-Layer Structure and Unit Boundary Rules

Core Principle: The Agent Layer is defined first, and the Package Layer implements it.

Dimension	Package Layer	Agent Layer
Unit Nature	Code Structure — Import boundary, public interface, unit of testing.	Runtime Role — Collaboration participant possessing judgment, triggers, and owned state that receives requests and emits results.
Boundary Criteria	Dependency direction, reusability, change impact radius.	Responsibility, trigger source, state ownership, discretionary judgment authority.
Independence Definition	No mutual imports; do not share persistence stores.	Agnostic of each other's internal state; communicates exclusively via Contract Requests, Contract Results, and Events.

• A single agent is implemented by one or more packages. A package can serve as a shared component across multiple agents.
• The Agent Layer consists of one primary user-facing conversational specialist agent (A0) and multiple support agents (A1, A4, A5, A6, A7, A8).

🎯 The 4 Mandatory Criteria for Defining an Agent

A functional unit is classified as an Agent if and only if it satisfies ALL FOUR conditions below. If even one is missing, it is implemented as a Package (Component):

1. Autonomous Trigger: Receives its own triggers (request, asynchronous event, cron schedule, or human interaction).
2. Discretionary Choice: Evaluates context and selects one out of multiple possible alternatives.
3. Contract Hand-off: Transmits its decision result to other participants strictly formatted as a formal contract.
4. Self-contained Failure Disposal: Autonomously emits its own failure resolution (partial result, pending hold, or human confirmation request).

Additional Structural Rules

• Deterministic calculation, validation rules, and persistence are always packages: Concept retrieval ranking (retrieval), guard verification (guard), evidence construction (evidence_view), counter-evidence inspection (critic), feedback routing (feedback), and calculation execution (calc_runner) are purely components.
• Separation of Judgment and Mechanism: If a feature involves both judgment and deterministic mechanics, place the judgment logic in the Agent and the execution mechanics in the Package.
• Universal pipelines are NOT agents: Mandatory pipeline segments (LLM hook chains, tracer, event bus) and pass-through parallel execution wrappers that do not make non-deterministic decisions are packages.

4-2 System Layer Hierarchy Diagram

TOP: Overall Platform (총괄)

Domain Workbench Composition · Lifecycle Management · Hook / Init / Carryover Function Registration

↓

UI Shell (Web / Frontend Interaction Layer)

↓

AGENT LAYER (Runtime Specialists)

A0 Dialogue (Specialist)

A1 Query Parse

A4 Evaluation

A5 Investigation

A6 Data Analysis

A7 Semantics

A8 Exploration

↓

Presentation

evidence_view, display_optimizer

User Ops

access, personalization, domain_lifecycle, llm_policy

Ingest

loader, user_input

Understanding

profile, connectivity, value_roles, meaning_structure

Knowledge

knowledge_policy, critic, pipeline_runner

Compute

grouping, calc_runner, derived_data, codegen

QA

conversation, query_slots, retrieval, guard

Quality

eval_lab, quality_metrics, feedback

↓

BASE FOUNDATION (Core Utilities & Infrastructure)

store · contracts · observability · parallel · algorithms · llm_gateway · code_sandbox

Hook Binding: guard & llm_policy register hooks into llm_gateway Event Bus: Base publishes events subscribed by UI & Agents Slots: Integrated Admin Agent & web_search connect as pure interfaces

4-3 Agent Layer Specifications

Each runtime agent operates autonomously within strict boundaries, communicating solely via formal contracts and events.

A0: Dialogue Specialist Agent (대화 에이전트)

Lead Specialist

Primary Responsibilities: User query reception and answer orchestration. Directly invokes retrieval for concept searches and guard for explanation verification. Connects evidence display, permission checks, personalization, and past answer reproducibility. Records used knowledge tiers, semantic rule IDs, node filters, outlier criteria, and agent questions. Dispatches execution requests (calc_runner.run_plan) and presents step reasons/data references. Never directly writes to understanding.

Triggers: UI queries, feedback comments, inclusion designations, answer replay requests, A4/A8 test queries.

Key Packages: Entire qa, compute, presentation, access, knowledge_policy, meaning_structure (read-only).

A1: Query Interpretation Agent (질의 해석 에이전트)

Support Agent

Extracts and validates slots (period, conditions, comparison baselines) from questions + provides calculation method hints + formulates execution plans (CalcPlan). Binds parameters if confirmed definitions exist; otherwise infers steps with unconfirmed badges. Drafts conversational calculation rules into CalcRule.

Trigger: A0 Query Interpretation Contract Request | Packages: query_slots, algorithms, meaning_structure, knowledge_policy, derived_data, connectivity, llm_gateway.

A4: Evaluation Agent (평가 에이전트)

Support Agent

Executes evaluation experiments, benchmarks variants, reports pass/regression metrics. Tests across backends, algorithms, and post-upload re-evaluations. Manages autonomous adjustment and automatic rollback of learning rate parameters. Formulates draft evaluation question sets using deterministic rules.

Trigger: UI Evaluation Request, Knowledge Changes, data_updated, Scheduled Runs | Packages: eval_lab, quality_metrics, knowledge_policy, A0 Request Contract.

A5: Investigation Coordination Agent (조사 조정 에이전트)

Support Agent

Automates investigation phases up to the human gate and manages checkpoint resumes (A6 Re-analysis Request → A7 Candidate Deliberation → Critic Validation → Tier Transition). Halts safely at human gates. Computes learning guidance (need, overhead, resources, limits) and produces investigation goals for repeated rejection signals or newly uploaded data.

Trigger: UI Start Investigation, Demand Accumulation, Domain Registration, Repeated Rejections | Packages: pipeline_runner, critic, knowledge_policy, A6/A7 Request Contracts.

A6: Data Analysis Agent (데이터 분석 에이전트)

Support Agent

Initiated upon file upload completion to build connectivity graphs. For incremental uploads, isolates changes and issues data_updated events. Proposes exclusion candidates, confirms user structural edits (structure_changed), handles node distinction modifications (confirmed_reuse), registers correction rules into knowledge_policy, manages rule rollbacks, and resolves user conflicts.

Trigger: Upload Completion, User Doc Registration, A5 Request, structure_edit, Revert Requests | Packages: ingest.loader, Entire understanding, algorithms, parallel, domain_lifecycle.

A7: Semantic Deliberation Agent (의미 협의 에이전트)

Support Agent

Deliberates node semantics post-connectivity. Emits meaning_changed on semantic rule updates, batches status/opinion changes (node_state_changed), resolves semantic conflicts (meaning_conflict), adjusts State Value ↔ Condition Value shifts, updates Concept Ledger, classifies outlier criteria, and processes semantic rollback requests.

Trigger: Connectivity Ready, structure_changed, apply_node_batch, A0 Meaning Requests | Packages: connectivity, value_roles, meaning_structure, knowledge_policy, critic.

A8: Exploratory Questioning Agent (탐구 질문 에이전트)

Support Agent

Proactively synthesizes, executes, and proposes insightful analytical questions before the user prompts them. Dispatches the Present Exploratory Question event to stimulate proactive domain discovery.

Trigger: Scheduled Cron Triggers, Knowledge Expansions | Packages: connectivity, quality_metrics, pipeline_runner, llm_gateway, A0 Request Contract.

4-4 Package Layer (33 Modules across 9 Intermediate Groups)

The deterministic mechanics of the system are divided into 33 packages across 9 functional groups. Every domain-scoped database query implicitly receives domain_id.

1. Ingest (loader, user_input) Source Ingestion & User Inputs

loader: load_file(domain_id, file, mode, provenance) -> LoadReport, resolve_choice(...), tables(domain_id) -> TableColumns. Owns domain raw tables and source loading versions.
user_input: accept_prior_info(...), accept_seed_questions(...), record_node_opinion(...), record_change_draft(...), set_draft_state(...), record_structure_edit(...). Owns the Fact Ledger (input documents, raw opinions, draft state transitions).

2. Understanding (profile, connectivity, value_roles, meaning_structure) Data Graph & Semantics

profile: profile_domain(...), render_guide(...), sample_rows(...), check_occurrence(...), check_format(...).
connectivity: Deterministic node identifiers, edge construction, alias ledgers. build(...), view(...), descendants(...), set_state(...), apply_edit(...), map_signature(...), compare_signatures(...).
value_roles: Node role classification, outlier criteria, segments. classify(...), detect_segments(...), set_role(...), set_outlier_criteria(...).
meaning_structure: Decoding rules and Concept Ledger. rule_for(...), decode(...), upsert_rule(...), upsert_concept(...), concepts(...).

3. Knowledge (knowledge_policy, critic, pipeline_runner) Policy, Verification & Workflow

knowledge_policy: Registry, tier transitions, approval histories, conflict tracking. register(...), transition(...), usable(...), affected(...), set_learning_param(...), rollback_learning_param(...).
critic: Deterministic counter-evidence testing. check(domain_id, candidate) -> CriticVerdict.
pipeline_runner: Declarative transition runner & human-gate coordinator. create_goal(...), record_demand(...), next_step(...), save_checkpoint(...).

4. Compute (grouping, calc_runner, derived_data, codegen) Deterministic Calculation & Execution

grouping: collect(domain_id, conditions, order, forced, rule_refs, node_filter, as_of) -> Batch.
calc_runner: run_plan(domain_id, plan, bindings, inputs, forced, rule_refs, node_filter, as_of) -> Result (Deterministic stepwise execution without LLM calls).
derived_data: define(...), materialize(...), lineage(...), mark_stale(...). Owns derived data & lineage graphs.
codegen: propose_and_run(spec) -> Candidate, adopt(candidate_id, approval).

5. QA (conversation, query_slots, retrieval, guard) Context, Extraction, Search & Safety

conversation: Thread context, pending selections, answer records, invalidation subscriptions. get_thread_context(...), save_turn(...), find_reusable(...), invalidate(...).
query_slots: Slot extraction & deterministic plan validation. extract_slots(...), validate(...), verify_plan(plan, refs) -> PlanCheck.
retrieval: N-gram and token-based concept matching. search_concepts(...), sync_index(...).
guard: Explanation verification and LLM gateway hook installer. verify_explanation(...), install_hooks(gateway).

6. Presentation (evidence_view, display_optimizer) Evidence Panels & Layout Optimization

evidence_view: Builds evidence panels, including included/excluded rows, exclusion reasons, knowledge tier badges, and node sample drill-downs. open_scope(...), build_evidence(...), expand(...), series(...).
display_optimizer: recommend(data_shape, user) -> DisplayPlan, recommend_layout(...).

7. User Ops (access, personalization, domain_lifecycle, llm_policy) Security, Domain Lifecycle & Quotas

access: Authentication, role-based authorization, node filters, user mapping. authorize(...), node_filter(...), assign_role(...).
personalization: Tracking user habits, domain know-how. update_from_turn(...), interests(...), knowhow(...).
domain_lifecycle: Bundles, carryover across domains, domain reset. create(...), export(...), import_bundle(...), prepare_carryover(...).
llm_policy: Egress scopes, paid consent, spending limits. install(gateway), set_cost_policy(...), record_paid_consent(...).

8. Quality (eval_lab, quality_metrics, feedback) Evaluation, Metrics & Feedback Routing

eval_lab: Experiment planning, 3-tier evaluator suite, prompt management. draft_question_set(...), confirm_question_set(...), plan_experiment(...), compare(...).
quality_metrics: System accuracy, repeated rejection tracking, correction frequency metrics. record(event), report(...).
feedback: Deterministic routing of positive/negative feedback, rejection logs. submit(...), route_unrouted(...).

9. Base Foundation (store, contracts, observability, parallel, algorithms, llm_gateway, code_sandbox) Core Infrastructure

store: Domain DBs, Integrated DB, Global Assets, schema migration idempotency.
contracts: Canonical definition of request envelopes, event envelopes, references, and shared models.
observability: Span tracing, unified event publishing/subscribing, heartbeat.
parallel: Thread-pool worker execution for read queries.
llm_gateway: Single point of entry for all LLM calls with hook chains and fallbacks.
code_sandbox: Resource-limited, isolated process runner for candidate code.

4-6 Dependency Rules & Interaction Paradigms

Interaction Model	Applicable Area	Governing Rule
Direct Function Call	Higher layer → Lower layer public interfaces	Never call private modules/functions prefixed with underscore (_).
Hook Registration	guard, llm_policy → llm_gateway	Registered during Top Platform bootstrap. llm_gateway does NOT import either module.
Event Pub/Sub	Publishers → observability bus → Subscribers	Publishers are unaware of subscribers. Subscriptions are wired during bootstrap.
Storage Mediation	All stateful modules with owned storage	Only the owning module writes to its tables. Others read exclusively via public query APIs.

🛡️ The 6 Cardinal Dependency Rules

1. Strict Top-Down Flow: Top Platform → UI Shell → Agent Layer → Feature Modules → Base Modules. Lateral module calls are strictly constrained to permitted dependencies with zero circularity.
2. Single-Writer Invariant on Understanding: ONLY A6 and A7 are authorized to invoke write methods on understanding. A0, A1, and A8 use read-only query interfaces.
3. Centralized Access Evaluation: access.authorize and access.node_filter are called ONLY at the A0 entry point and UI Shell layout construction. No other module evaluates permissions.
4. Decoupled LLM Gateway: guard and llm_policy attach exclusively via hook registration. llm_gateway never imports them.
5. No Direct Cross-Agent Invocations: Agents NEVER call one another directly. All cross-agent collaborations (e.g. A0 requesting A1 parsing, A5 delegating to A6/A7) occur via contract requests and asynchronous events.
6. Delegated Lifecycle Cleanups: Domain reset and carryovers are registered by the Top Platform via modular callbacks (domain_lifecycle.register_reset). domain_lifecycle never imports specific domain modules.

4-7 Major, Mid, and Subgroup Taxonomy

The system organizes packages into 5 Major Groups (A ~ E) for administrative scoping. Major groups do not represent physical code layers.

Major Group	Mid-Group	Included Packages	Count	Depends On
A. Base Foundation	Base	store, contracts, observability, parallel, algorithms, llm_gateway, code_sandbox	7	None (Lowest Layer)
B. Data Understanding	ingest	loader, user_input	2	A
	understanding	profile, connectivity, value_roles, meaning_structure	4	A
C. User Operations	user_ops	access, personalization, domain_lifecycle, llm_policy	4	A
D. Knowledge, Computation & Response	knowledge	knowledge_policy, critic, pipeline_runner	3	A, B
	compute	grouping, calc_runner, derived_data, codegen	4	A, B
	qa	conversation, query_slots, retrieval, guard	4	A (intra-group: knowledge)
	presentation	evidence_view, display_optimizer	2	A, B, C (intra-group: compute)
E. Quality Assurance	quality	eval_lab, quality_metrics, feedback	3	A, D
Total Architecture Scope		9 Intermediate Groups	33	E → D → (B, C) → A

4-8 Dual Constants Architecture

To eliminate magic numbers, hardcoded URLs, and configuration leaks, all constant values are segregated into two distinct systems:

1. Shared Constants (공유 상수)

Cross-module parameters such as server port configurations (UI_PORT), deployment install parameters (default admin account seeds, OAuth client keys), and declarative state machine transition tables.

2. Policy Constants (정책 상수)

Module-scoped defaults, upper bounds, and operational thresholds: Learning rate baseline/boundaries, context inheritance turn count, extraction retry limits, n-gram lengths, and minimum matching scores. Prefix-isolated by module.

4-9 Independence Principles & Verification Checks

#	Independence Invariant	Automated Verification Strategy
1	Never import internal modules of other units — use public interfaces only.	Construct AST import graphs to detect layer violations and private module references.
2	Never access another unit's storage tables directly via SQL.	Audit SQL string table names against store table ownership registries.
3	Units remain fully functional according to contract when dependencies are stubbed.	Run unit contract tests and integration suites with mock test doubles inserted.
4	Unit tests execute without concrete implementations of other units.	Execute test runs with cross-module imports blocked at the runtime loader level.
5	Zero circular dependencies allowed anywhere in the codebase.	Run topological sort cycles detection across the complete AST import graph.
6	Agents communicate solely via contract requests, results, and events.	Verify zero cross-agent module imports and validate strict schema payloads.
7	System gracefully degrades (partial answer / pending hold) if any support agent stops.	Fault-injection integration tests with individual support agents deactivated.

Inevitable Shared Substrates & Strict Boundaries

• store: Tables are exclusively written by owner modules; external access is query-only via public APIs.
• contracts: Canonical source of truth for shared requests, results, events, and span models.
• llm_gateway: All LLM invocations pass through uniform hook chains (data egress, budget caps, value matching guards).
• observability: Centralized owner of span models and telemetry storage; other units interact solely via the span interface.

#SoftwareArchitecture #MultiAgentSystems #SystemDesign #Biligent #AIWorkflow

© Biligent Architecture Series. All rights reserved.