AI Framework Documentation

Overview

The FinAegis AI Framework enables autonomous agents to interact with the full banking platform. It provides Model Context Protocol (MCP) tools for LLM integration, Google A2A protocol for agent-to-agent communication, and x402-based micropayments for pay-per-request API access.

Architecture

The AI Framework spans three domain modules: AgentProtocol for A2A communication, X402 for payment gating, and AI for MCP tool definitions.

app/
├── Domain/
│   ├── AgentProtocol/     # Google A2A protocol implementation
│   │   ├── Services/      # AgentPaymentIntegrationService
│   │   └── Models/        # AgentCard, AgentTask
│   ├── X402/              # HTTP 402 payment gate
│   │   ├── Services/      # Settlement, Verification, Pricing
│   │   └── Middleware/     # X402PaymentGateMiddleware
│   └── AI/                # MCP tool definitions
│       └── Tools/         # TransactionQueryTool, X402PaymentTool
└── Infrastructure/
    └── AI/                # Provider adapters

MCP Tools

FinAegis implements Model Context Protocol tools that LLMs like Claude can use to interact with the banking platform. Tools are registered as MCP-compatible endpoints.

TransactionQueryTool

Translates natural language questions about transactions, balances, and portfolios into structured database queries. Supports filtering by date range, amount, asset type, and counterparty.

X402PaymentTool

Enables agents to make USDC payments for API access using the x402 protocol. Handles payment negotiation, execution, and verification in a single tool call.

A2A Protocol

The Agent-to-Agent (A2A) protocol, based on Google's specification, enables agents to discover each other's capabilities, negotiate tasks, and collaborate on multi-step financial workflows.

Agent Cards

Each agent publishes a capability card describing its skills, input/output schemas, and pricing. Other agents can discover these cards and delegate appropriate tasks.

Task Lifecycle

Tasks follow a lifecycle: created → assigned → in_progress → completed. Agents report progress and intermediate results through the A2A message channel.

x402 Agent Payments

The x402 protocol enables HTTP-native micropayments. When an agent hits a payment-gated endpoint, it receives a 402 Payment Required response with pricing details. The agent then submits a USDC payment and retries the request.

# 1. Agent calls a gated endpoint
GET /api/v2/premium/data
→ 402 Payment Required
# X-Payment-Required: {"amount": "0.01", "currency": "USDC", "network": "base"}

# 2. Agent submits payment
POST /api/v2/x402/pay
# {"endpoint": "/api/v2/premium/data", "tx_hash": "0x..."}

# 3. Agent retries with payment proof
GET /api/v2/premium/data
# X-Payment-Proof: 0x...
→ 200 OK

Spending Controls

Safety rails for autonomous agents. Configure per-agent daily and monthly spending limits, per-request caps, and approval thresholds. The X402PricingService enforces limits before any payment is authorized.

• Per-agent daily and monthly spending caps
• Per-request maximum amount
• Approval workflows for high-value transactions
• Real-time spending dashboards

Transaction Query

The TransactionQueryTool enables natural language interaction with transaction data. Agents can ask questions and receive structured results.