[Feat]: Define structured Risk Payload schema for Section 7.4 Risk Signals

[ravyg]

Is your feature request related to a problem? Please describe.

The AP2 specification (Section 7.4) acknowledges critical risk considerations for agent-initiated payments but explicitly leaves the Risk field intentionally left open-ended:

The v0.1 implementation includes a Risk field in the JSON exchange between the various entities but it is intentionally left open-ended for now since we expect different players in the industry to assess the right signals which should be included based on different risk appetites and business models.

The A2A extension similarly states that risk_data contains "implementation-defined risk signals" without providing a schema.

This creates challenges:

1. Interoperability: Different implementations will define incompatible risk schemas
2. Network/Issuer trust: Payment networks cannot reason about risk without standardized signals
3. Missing runtime governance: AP2 mandates validate authority at signing time, but don't address cumulative, velocity, or anomalous behaviors that emerge at execution time

Specific gaps identified in Section 7.4:

• "Temporal Gaps: Payment method tokens may be generated significantly before a transaction is executed"
• "User Asynchronicity: The user may no longer be in-session for the entire payment journey"
• "Agent Identity: The Shopping Agent's ID becomes synonymous with a bot's identity, which requires new methods of verification and trust"

Describe the solution you'd like

Propose a Fiduciary Circuit Breaker (FCB) extension that provides a structured schema for the Risk Payload, including:

1. Trip Condition Types

Standardized categories of runtime risk checks:

• VALUE_THRESHOLD - Transaction exceeds monetary limit
• CUMULATIVE_THRESHOLD - Running totals exceed threshold
• VELOCITY - Too many actions too quickly
• AUTHORITY_SCOPE - Action outside delegated domain
• ANOMALY - ML model detects unusual pattern
• TIME_BASED - Action during restricted period
• DEVIATION - Significant departure from baseline

2. FCB State Machine

Runtime governance states:

• CLOSED - Normal operation, agent acts autonomously
• OPEN - All actions blocked, requires human review
• HALF_OPEN - Limited operations with enhanced monitoring
• TERMINATED - Permanently halted

3. Human Escalation Protocol

Structured format for escalation context when FCB trips, enabling human-in-the-loop review.

4. Risk Payload Schema

A well-defined RiskPayload type that can be included in:

• IntentMandate messages
• CartMandate artifacts
• PaymentMandate messages

Proposed Types (Python)

class TripConditionType(str, Enum):
    VALUE_THRESHOLD = "VALUE_THRESHOLD"
    CUMULATIVE_THRESHOLD = "CUMULATIVE_THRESHOLD"
    VELOCITY = "VELOCITY"
    AUTHORITY_SCOPE = "AUTHORITY_SCOPE"
    ANOMALY = "ANOMALY"
    TIME_BASED = "TIME_BASED"
    DEVIATION = "DEVIATION"

class TripConditionStatus(str, Enum):
    PASS = "PASS"
    FAIL = "FAIL"
    WARNING = "WARNING"

class FCBState(str, Enum):
    CLOSED = "CLOSED"
    OPEN = "OPEN"
    HALF_OPEN = "HALF_OPEN"
    TERMINATED = "TERMINATED"

class TripConditionResult(BaseModel):
    condition_type: TripConditionType
    status: TripConditionStatus
    threshold: Optional[float] = None
    actual_value: Optional[float] = None
    message: Optional[str] = None

class HumanEscalation(BaseModel):
    escalation_id: str
    approver_id: Optional[str] = None
    decision: Optional[str] = None  # APPROVE, APPROVE_WITH_CONDITIONS, REJECT
    conditions: Optional[list[str]] = None
    timestamp: Optional[str] = None

class FCBEvaluation(BaseModel):
    fcb_state: FCBState
    trips_evaluated: int
    trips_triggered: int
    trip_results: list[TripConditionResult]
    risk_score: Optional[float] = None  # 0.0 to 1.0
    human_escalation: Optional[HumanEscalation] = None

class RiskPayload(BaseModel):
    fcb_evaluation: Optional[FCBEvaluation] = None
    agent_modality: str  # "HUMAN_PRESENT" or "HUMAN_NOT_PRESENT"
    session_id: Optional[str] = None
    custom_signals: Optional[dict[str, Any]] = None

---

Describe alternatives you've considered

1. Leave as implementation-defined: Current approach, but leads to fragmentation
2. Simple risk score only: Less granular, doesn't capture specific trip conditions
3. Defer to payment networks: Each network defines their own, but AP2 loses interoperability value

Additional context

Relationship to AP2 Mandates

FCB complements (not replaces) the existing mandate system:

Layer	AP2 Component	Question Answered
Authorization	IntentMandate/CartMandate	"Does agent have proof of authority?"
Runtime Governance	FCB RiskPayload	"Should this action proceed right now?"

Example Use Case

Agent has valid IntentMandate with $50,000 budget:

1. Agent attempts $45,000 purchase ✓ (within mandate)
2. FCB checks: Agent already spent $30,000 today across 5 transactions
3. FCB trips on CUMULATIVE_THRESHOLD (daily limit exceeded)
4. Human escalation triggered with full context
5. Human approves → FCB state moves to HALF_OPEN
6. Transaction proceeds with RiskPayload attached to PaymentMandate
7. Network/Issuer can factor FCB approval into authorization decision

Benefits

1. Standardized risk signals for network/issuer visibility
2. Human-in-the-loop escalation protocol for edge cases
3. Fills Section 7.4 gap with concrete implementation
4. Backward compatible - existing implementations can ignore if not needed

---

Deliverables

If this proposal is accepted, I will contribute:

1. src/ap2/types/risk.py - Python type definitions
2. samples/go/pkg/ap2/types/risk.go - Go type definitions
3. docs/topics/fiduciary-circuit-breaker.md - Documentation
4. Updates to a2a-extension.md to reference the new types
5. Example usage in samples

---

Related Issues

This proposal complements but does not duplicate existing issues:

Issue	Relationship
#46 - Audit log format	FCB provides structured data that could be logged; #46 focuses on log format, this focuses on runtime governance
#51 - Supporting Issuers & Networks	FCB provides standardized risk signals that issuers/networks can consume; addresses "how to share" with structured schema
#44 - Handling failure states	FCB defines state machine for trip conditions; complements failure handling with runtime governance

---

Implementation Status

I have a working implementation ready to contribute:

Component	Status
src/ap2/types/risk.py	✅ Complete with tests (22 passing)
samples/go/pkg/ap2/types/risk.go	✅ Complete with tests (11 passing)
docs/topics/fiduciary-circuit-breaker.md	✅ Complete
Unit tests	✅ 33 tests passing

Branch: feature/fcb-risk-extension at https://github.com/ravyg/AP2

---

References

• AP2 Specification Section 7.4: Risk Signals
• Circuit Breaker Pattern - Michael Nygard, Release It! (2007)
• Fiduciary Duty - Legal concept of acting in another's best interest

---

Author: Ravish Gupta (IEEE Senior Member)
Date: February 2026

Code of Conduct

• I agree to follow this project's Code of Conduct