The HITL specification from Page 04 is the input. Every checkpoint defined there is implemented here as a formal state machine node — with an entry condition, a presentation contract, a timeout, and an immutable audit record. This is not a diagram of agents. It is an architecture of agents.
The AE agent swarm uses Google ADK for agent definition, A2A protocol for inter-agent communication, and MCP for tool access. The Orchestrator is the single point of task dispatch — it never executes business logic directly. Specialist agents are stateless and idempotent. All state lives in Firestore. All tool calls are audited.
The Orchestrator is the only agent that receives external requests. It never executes business logic directly. It decomposes tasks, routes sub-tasks to specialist agents via A2A, tracks task completion across the swarm, handles agent failures via circuit breaker, and maintains the global conversation context. It is the only agent with write access to the Orchestrator state collection in Firestore.
Each specialist agent is defined by three things: its state machine (what states it can be in and what triggers each transition), its tool manifest (the exact MCP tools it is permitted to call), and its autonomy boundary (the line between what it does autonomously and what it escalates to a human). These are not descriptions — they are specifications.
Agent-to-Agent (A2A) is the communication protocol between the Orchestrator and specialist agents. Every message is typed, versioned, and auditable. The sequence below shows a ContractGuard task dispatch and the HITL escalation that follows. The JSON schema below it is the actual message format.
{
"a2a_version": "1.0",
"message_type": "TASK_DISPATCH", // TASK_DISPATCH | TASK_ACK | TASK_UPDATE | TASK_COMPLETE | TASK_ERROR
"task_id": "task_cg_20260315_001a", // globally unique · format: task_{agent}_{date}_{seq}
"correlation_id": "orch_20260315_042", // orchestration session ID · links all sub-tasks
"from_agent": "orchestrator",
"to_agent": "contractguard",
"timestamp_utc": "2026-03-15T09:14:32Z",
"task_type": "CONTRACT_ANALYSIS",
"priority": "NORMAL", // NORMAL | HIGH | CRITICAL
"timeout_seconds": 3600, // 1 hour · circuit breaker triggers at 3 failures
"payload": {
"contract_id": "sfdc_contract_CV2026_0042",
"gcs_uri": "gs://claravis-contracts-eu/2026/0042_uniklinik.pdf",
"counterparty": "Universitätsklinikum München",
"contract_value_eur": 2840000,
"analysis_config": {
"risk_threshold": 0.65, // clauses above this score → HITL-02
"governing_law_check": "true", // always trigger HITL-03 if non-standard
"precedent_count": 3, // number of similar precedents to surface in HITL
"generate_counter": "post_hitl_approval"
}
},
"audit": {
"initiated_by": "orchestrator-sa@claravis-ae-prod.iam.gserviceaccount.com",
"audit_trail_id": "audit_20260315_cg_001a", // Firestore document ID · immutable
"parent_hitl_ids": [] // populated when this task is triggered by a HITL decision
}
}
{
"a2a_version": "1.0",
"message_type": "TASK_UPDATE",
"task_id": "task_cg_20260315_001a",
"from_agent": "contractguard",
"to_agent": "orchestrator",
"timestamp_utc": "2026-03-15T09:42:18Z",
"state": "HITL_PAUSE",
"hitl_context": {
"hitl_spec_id": "HITL-02", // references Page 04 HITL specification
"hitl_event_id": "hitl_20260315_cg_007", // Firestore document ID · immutable on creation
"approver_role": "GENERAL_COUNSEL",
"sla_deadline_utc": "2026-03-16T09:42:18Z", // 24-hour SLA per HITL-02 spec
"timeout_action": "ESCALATE_TO_GC_MANAGER",
"presented_to_human": {
"clause_text": "Liability limited to 50% of contract value...",
"risk_score": 0.82,
"shap_attribution": [
{ "feature": "liability_cap_ratio", "value": 0.5, "contribution": +0.31 },
{ "feature": "governing_law_match", "value": "false", "contribution": +0.24 },
{ "feature": "indemnification_asymmetry", "value": 0.78, "contribution": +0.18 }
],
"precedent_contracts": [
{ "id": "sfdc_contract_CV2024_0108", "similarity": 0.91, "outcome": "negotiated_up_to_80pct" },
{ "id": "sfdc_contract_CV2025_0033", "similarity": 0.87, "outcome": "accepted_with_carve_out" }
],
"decision_options": ["APPROVE_AS_IS", "REQUEST_REVISION", "ESCALATE_EXTERNAL_COUNSEL"]
}
}
}
Agent memory is not a monolith. Short-term memory holds the context for the current task — it is ephemeral and task-scoped. Long-term memory holds the institutional knowledge that makes agents smarter over time — contract precedents, historical decisions, asset failure patterns. The shared context bus is the event stream that keeps all agents aware of what other agents are doing.
A production-grade agent swarm is defined as much by its failure modes as its happy path. Every guardrail below is a design artifact — not a monitoring dashboard added after the fact. The circuit breaker, confidence thresholds, hallucination detection, and fallback behaviours are specified before a line of agent code is written.
ADR-007 through ADR-009 are produced in the agent swarm design phase. Each states the choice, the alternatives that were evaluated, and why this choice was made — the reasoning that a principal engineer or enterprise architect will probe in any serious design review.
The agent specifications on this page reference ML models by name — asc606_model.classify, rul_model.predict, anomaly_model.score_event. Page 06 designs those models from the ground up: feature engineering, training pipelines, SHAP explanation contracts, Model Cards, MLOps, and drift detection.