feat(types): add Fiduciary Circuit Breaker risk extension#164
feat(types): add Fiduciary Circuit Breaker risk extension#164ravyg wants to merge 3 commits intogoogle-agentic-commerce:mainfrom
Conversation
Summary of ChangesHello @ravyg, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request integrates the Fiduciary Circuit Breaker (FCB) into the Agent Payments Protocol (AP2), enhancing the protocol's ability to monitor and govern autonomous agent behavior in real-time. By introducing structured risk types and a state-based control mechanism, the FCB allows for dynamic assessment of transaction risks, enabling automated intervention or human escalation when predefined conditions are met. This ensures agents operate within acceptable risk parameters, providing greater security and trust in automated financial transactions. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant and well-designed Fiduciary Circuit Breaker (FCB) extension for risk management. The changes include new data types for Python and Go, comprehensive documentation, and thorough test suites. The code quality is high, with excellent use of language features like pydantic in Python and idiomatic patterns in Go. My review includes a few minor suggestions to further improve the clarity of the documentation and enhance test coverage for edge cases.
| ```go | ||
| import "github.com/google-agentic-commerce/ap2/samples/go/pkg/ap2/types" | ||
|
|
||
| // Create an FCB evaluation | ||
| evaluation := types.NewFCBEvaluation(types.FCBStateClosed) | ||
| evaluation.AddTripResult(types.TripConditionResult{ | ||
| ConditionType: types.TripConditionValueThreshold, | ||
| Status: types.TripConditionStatusPass, | ||
| Threshold: floatPtr(100000), | ||
| ActualValue: floatPtr(45000), | ||
| }) | ||
| evaluation.RiskScore = floatPtr(0.15) | ||
|
|
||
| // Create risk payload | ||
| riskPayload := types.NewRiskPayload(types.AgentModalityHumanNotPresent) | ||
| riskPayload.FCBEvaluation = evaluation | ||
| riskPayload.AgentID = stringPtr("agent_xyz") | ||
| ``` |
There was a problem hiding this comment.
The Go code example uses helper functions floatPtr and stringPtr which are not defined in the standard library or within this project's provided code. This could be confusing for users trying to run the example. For better clarity and to make the example self-contained, I suggest showing how to create pointers explicitly, similar to the pattern used in the Go test files.
| ```go | |
| import "github.com/google-agentic-commerce/ap2/samples/go/pkg/ap2/types" | |
| // Create an FCB evaluation | |
| evaluation := types.NewFCBEvaluation(types.FCBStateClosed) | |
| evaluation.AddTripResult(types.TripConditionResult{ | |
| ConditionType: types.TripConditionValueThreshold, | |
| Status: types.TripConditionStatusPass, | |
| Threshold: floatPtr(100000), | |
| ActualValue: floatPtr(45000), | |
| }) | |
| evaluation.RiskScore = floatPtr(0.15) | |
| // Create risk payload | |
| riskPayload := types.NewRiskPayload(types.AgentModalityHumanNotPresent) | |
| riskPayload.FCBEvaluation = evaluation | |
| riskPayload.AgentID = stringPtr("agent_xyz") | |
| ``` | |
| import "github.com/google-agentic-commerce/ap2/samples/go/pkg/ap2/types" | |
| // Create an FCB evaluation | |
| evaluation := types.NewFCBEvaluation(types.FCBStateClosed) | |
| threshold := 100000.0 | |
| actualValue := 45000.0 | |
| riskScore := 0.15 | |
| evaluation.AddTripResult(types.TripConditionResult{ | |
| ConditionType: types.TripConditionValueThreshold, | |
| Status: types.TripConditionStatusPass, | |
| Threshold: &threshold, | |
| ActualValue: &actualValue, | |
| }) | |
| evaluation.RiskScore = &riskScore | |
| // Create risk payload | |
| riskPayload := types.NewRiskPayload(types.AgentModalityHumanNotPresent) | |
| riskPayload.FCBEvaluation = evaluation | |
| agentID := "agent_xyz" | |
| riskPayload.AgentID = &agentID |
| | State | Behavior | Entry Condition | | ||
| |-------|----------|-----------------| | ||
| | **CLOSED** | Normal operation. Agent acts autonomously. | Initial state; or human approves | | ||
| | **OPEN** | All actions blocked. Requires human review. | Any trip condition fails | | ||
| | **HALF_OPEN** | Limited operations with enhanced monitoring. | Human approves with conditions | | ||
| | **TERMINATED** | Permanently halted. No recovery. | Human rejects; or timeout | |
There was a problem hiding this comment.
The state transition diagram on lines 69-85 provides more detail on state transitions than this table of FCB states. To improve clarity and consistency, consider updating the "Entry Condition" column to reflect all possible transitions shown in the diagram. For example:
- The entry condition for
CLOSEDcould also include transitioning fromHALF_OPENwhen "conditions are met". - The entry condition for
OPENcould also include transitioning fromHALF_OPENwhen "conditions are violated".
| def test_risk_score_bounds(self): | ||
| """Test risk_score validation.""" | ||
| # Valid score | ||
| eval = FCBEvaluation( | ||
| fcb_state=FCBState.CLOSED, | ||
| trips_evaluated=1, | ||
| trips_triggered=0, | ||
| risk_score=0.5, | ||
| ) | ||
| assert eval.risk_score == 0.5 | ||
|
|
||
| # Score at boundaries | ||
| eval_min = FCBEvaluation( | ||
| fcb_state=FCBState.CLOSED, | ||
| trips_evaluated=1, | ||
| trips_triggered=0, | ||
| risk_score=0.0, | ||
| ) | ||
| assert eval_min.risk_score == 0.0 | ||
|
|
||
| eval_max = FCBEvaluation( | ||
| fcb_state=FCBState.CLOSED, | ||
| trips_evaluated=1, | ||
| trips_triggered=0, | ||
| risk_score=1.0, | ||
| ) | ||
| assert eval_max.risk_score == 1.0 |
There was a problem hiding this comment.
The test_risk_score_bounds test currently only verifies valid risk_score values. To make the test more robust, I suggest adding cases to verify that pydantic.ValidationError is raised for out-of-bounds values (e.g., < 0.0 or > 1.0), ensuring the validation constraints are enforced correctly.
def test_risk_score_bounds(self):
"""Test risk_score validation."""
from pydantic import ValidationError
# Valid score
eval = FCBEvaluation(
fcb_state=FCBState.CLOSED,
trips_evaluated=1,
trips_triggered=0,
risk_score=0.5,
)
assert eval.risk_score == 0.5
# Score at boundaries
eval_min = FCBEvaluation(
fcb_state=FCBState.CLOSED,
trips_evaluated=1,
trips_triggered=0,
risk_score=0.0,
)
assert eval_min.risk_score == 0.0
eval_max = FCBEvaluation(
fcb_state=FCBState.CLOSED,
trips_evaluated=1,
trips_triggered=0,
risk_score=1.0,
)
assert eval_max.risk_score == 1.0
# Invalid scores
with pytest.raises(ValidationError):
FCBEvaluation(
fcb_state=FCBState.CLOSED,
trips_evaluated=1,
trips_triggered=0,
risk_score=-0.1,
)
with pytest.raises(ValidationError):
FCBEvaluation(
fcb_state=FCBState.CLOSED,
trips_evaluated=1,
trips_triggered=0,
risk_score=1.1,
)
ravyg
force-pushed
the
fcb-governance
branch
2 times, most recently
from
8fc10ee to
d3686b5
Compare
This PR implements structured risk types for AP2 Section 7.4 (Risk Signals), which was "intentionally left open-ended" in the v0.1 specification. The Fiduciary Circuit Breaker (FCB) pattern provides runtime governance for autonomous agent transactions through: - Trip conditions that evaluate agent behavior against predefined thresholds (VALUE_THRESHOLD, CUMULATIVE_THRESHOLD, VELOCITY, ANOMALY, etc.) - A state machine for governance (CLOSED → OPEN → HALF_OPEN → TERMINATED) - Human escalation protocol for exceptional cases - Structured risk signals for network/issuer visibility Changes: - Add src/ap2/types/risk.py with Python type definitions - Add samples/go/pkg/ap2/types/risk.go with Go type definitions - Add docs/topics/fiduciary-circuit-breaker.md with documentation - Update src/ap2/types/__init__.py to export new types - Update mkdocs.yml to include FCB in navigation This addresses the gap identified in Section 7.4 where temporal gaps, user asynchronicity, and agent identity verification require runtime governance beyond what mandate-based authorization provides.> test: Add unit tests for FCB risk types Add comprehensive unit tests for the Fiduciary Circuit Breaker (FCB) risk extension types: Go tests (samples/go/pkg/ap2/types/risk_test.go): - 11 tests covering type constants, helper methods, JSON serialization - Tests for NewHumanEscalation, NewFCBEvaluation, AddTripResult - Complete integration scenario test Python tests (tests/test_risk.py): - 22 tests covering all enum types and Pydantic models - JSON round-trip serialization tests - B2B quote negotiation integration scenario Also includes minor formatting fix to risk.go (whitespace alignment). chore: add gitleaks config to allowlist AP2 data key constants The data key constants like 'ap2.risk.FCBEvaluation' are namespace identifiers, not secrets. This config prevents false positive alerts.
1 participant
Summary
Adds structured risk signal types for AP2 Section 7.4 (Risk Signals), introducing a Fiduciary Circuit Breaker (FCB) pattern for runtime governance of autonomous agent transactions.
FCB enables standardized trip conditions, state-based controls, and human escalation to mitigate risky or anomalous behavior beyond mandate-based authorization.
Changes
src/ap2/types/risk.pysamples/go/pkg/ap2/types/risk.godocs/topics/fiduciary-circuit-breaker.mdsrc/ap2/types/__init__.pymkdocs.ymlFeatures
CLOSED → OPEN → HALF_OPEN → TERMINATEDTests
risk.goCompatibility
Additive only — no breaking changes.
Fixes #163