Safe Agentic Payment System

Overview

This system demonstrates how AI agents can safely handle financial transactions by combining LLM-based intent generation with deterministic policy evaluation.

Challenge: How do we give AI agents autonomy to execute payments while maintaining strict safety controls?

Solution: Separate the probabilistic (LLM orchestration) from the deterministic (policy enforcement).

---

Functionalites

• Deterministic policy evaluation, fail-safe defaults, immutable audit trails
• Hexagonal design enables easy testing and infrastructure swapping
• Agent learns from policy rejections and adapts behavior
• Every decision logged for compliance and debugging

---

Architecture

graph TB
    subgraph primary["PRIMARY ADAPTERS (Driving)"]
        REST[FastAPI REST API]
    end

    subgraph domain["DOMAIN CORE (Business Logic)"]
        direction TB
        Agent[Payment Agent Service<br/>Orchestrates payment flow]
        Policy[Policy Engine<br/>Evaluates business rules]
        Models[Domain Models<br/>PaymentIntent, PolicyDecision,<br/>TransactionReceipt, PaymentSession]
        
        Agent -->|evaluates via| Policy
    end

    subgraph ports["PORTS (Interfaces)"]
        LLMPort[LLM Port]
        ExecPort[Execution Port]
        StoragePort[Storage Port]
        AuditPort[Audit Port]
    end

    subgraph secondary["SECONDARY ADAPTERS (Driven)"]
        OpenAI[OpenAI LLM Adapter]
        MockPay[Mock Payment Adapter]
        InMemStorage[InMemory Storage]
        InMemAudit[InMemory Audit]
    end

    REST -->|Execute Payment Goal| Agent

    Agent -.->|depends on| LLMPort
    Agent -.->|depends on| ExecPort
    Agent -.->|depends on| StoragePort
    Agent -.->|depends on| AuditPort

    LLMPort -.->|implemented by| OpenAI
    ExecPort -.->|implemented by| MockPay
    StoragePort -.->|implemented by| InMemStorage
    AuditPort -.->|implemented by| InMemAudit

    classDef primaryStyle fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef domainStyle fill:#fff3e0,stroke:#e65100,stroke-width:3px
    classDef portStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef secondaryStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

    class REST primaryStyle
    class Agent,Policy,Models domainStyle
    class LLMPort,ExecPort,StoragePort,AuditPort portStyle
    class OpenAI,MockPay,InMemStorage,InMemAudit secondaryStyle

Loading

Architecture Benefits:

• Core business logic fully testable without infrastructure
• Easy to swap implementations (mock → Stripe, in-memory → PostgreSQL)
• Clear separation between domain rules and technical concerns

---

Quick Start

Prerequisites

• Docker & Docker Compose
• OpenAI API key

Running the System

1. Create .env file in src/ directory:

   OPENAI_API_KEY=your_openai_api_key_here

2. Start server:

   make up

3. Test the agent:

   Navigate to src/tests/manual/agent.http and use REST Client extension.

   Example request:

   POST http://localhost:8000/agent/execute
   Content-Type: application/json
   
   {
     "goal": "Buy a MacBook Pro for new engineer"
   }

4. View API docs: http://localhost:8000/docs

5. Stop server:

   make down

---

How It Works

1. User provides goal (payment request)
2. Agent generates intent (structured payment intent)
3. Policy evaluation (Deterministic rules check if payment is allowed)
4. Execute or retry (If approved, execute; if denied, agent receives feedback and retries)
5. Audit logging (All decisions recorded for compliance)

Example Flow:

Goal: "Buy laptop for £2000"
  → Intent: {amount: 2000, beneficiary: "Apple", category: "equipment"}
  → Policy: ✓ Amount within limit, ✓ Category allowed
  → Execute: Payment successful
  → Audit: Session logged

---

Considerations

This is a demonstration system. Production deployment would require:

• Authentication & authorization
• Database persistence (PostgreSQL)
• Real payment provider integration (Stripe/Adyen)
• Enhanced observability (structured logging, metrics)
• Idempotency and retry logic
• Rate limiting and circuit breakers

---

Tech Stack

• Python 3.11+ with FastAPI
• OpenAI API for LLM orchestration
• Pydantic for type-safe data validation
• Docker for containerization

---

License