Aura — Autonomous Reliable Agentic Commerce

Multi-agent B2B procurement with built-in KYC/AML compliance and verifiable payment.

---

What is Aura?

Aura automates the full B2B procurement lifecycle — from vendor discovery to payment settlement — using a squad of autonomous AI agents. Unlike traditional shopping bots, Aura integrates Real-time KYC/AML compliance and cryptographically verifiable payment mandates before any transaction is settled.

Built for: Google AI Agent Labs Oslo 2026 — Team 6

---

The Agent Squad

Agent	Title	Responsibility	Protocol
Architect	🏛️ Procurement Officer	Parses user intent and orchestrates the full agent pipeline end-to-end	Google ADK SequentialAgent
Governor	⚖️ Finance Controller	Evaluates the procurement request against org spending rules before any vendor is contacted	Internal Policy Engine
Scout	🔭 Category Manager	Queries /.well-known/ucp endpoints to discover vendors, fetch pricing tiers, and rank candidates	UCP /.well-known/ucp
Sentinel	🛡️ Compliance Officer	Screens every shortlisted vendor against AML blacklists and KYC rules via the Core Banking System	BMS Compliance API
Closer	💳 Payment Manager	Signs a W3C Verifiable Credential Intent Mandate and settles payment through the AP2 gateway	AP2 IntentMandate + ECDSA-P256

flowchart LR
    User(["👤 User"])
    Architect["🏛️ Architect<br/><i>Procurement Officer</i>"]
    Governor["⚖️ Governor<br/><i>Finance Controller</i>"]
    Scout["🔭 Scout<br/><i>Category Manager</i>"]
    Sentinel["🛡️ Sentinel<br/><i>Compliance Officer</i>"]
    Closer["💳 Closer<br/><i>Payment Manager</i>"]
    Settlement(["✅ Settled"])
    Blocked(["⛔ Blocked"])

    User -->|"procurement request"| Architect
    Architect -->|"orchestrates"| Governor
    Governor -->|"policy: ALLOW"| Scout
    Governor -->|"policy: BLOCK"| Blocked
    Scout -->|"ranked vendor list"| Sentinel
    Sentinel -->|"KYC: APPROVED"| Closer
    Sentinel -->|"KYC: BLOCKED"| Blocked
    Closer -->|"AP2 mandate settled"| Settlement

Loading

---

Quick Start

Prerequisites

• Python 3.12+
• Google Cloud project with Vertex AI enabled (ai-agent-labs-oslo-26-team-6)
• Application Default Credentials: gcloud auth application-default login

Install & Run

# Clone and enter
git clone https://github.com/shailwx/aura && cd aura

# Set up virtualenv
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env if needed (project/region already pre-configured)

# Launch ADK dev UI — full browser-based agent playground
adk web

# Or run the FastAPI server directly
uvicorn main:app --reload --port 8080

Try it

# Happy path — legitimate vendor
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Buy 3 Laptop Pro 15 units from the best vendor"}'

# Blocked path — triggers Sentinel compliance block
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Buy laptops from ShadowHardware"}'

See API Reference for full endpoint documentation.

API Authentication (Optional)

Aura can run with JWT auth enabled for /run and /run/stream.

# .env
AUTH_ENABLED=true
AUTH_JWT_SECRET=replace-with-strong-secret
AUTH_JWT_ALGORITHM=HS256
AUTH_ALLOWED_ROLES=procurement_runner,admin

When enabled, call endpoints with a bearer token containing at least:

• sub (caller identity)
• role (must be in AUTH_ALLOWED_ROLES)

Example request:

curl -X POST http://localhost:8080/run \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Buy 3 Laptop Pro 15 units"}'

Session Backend (In-Memory or Redis)

Aura uses SESSION_BACKEND to choose session persistence:

# default dev mode
SESSION_BACKEND=inmemory

# durable mode
SESSION_BACKEND=redis
REDIS_URL=redis://localhost:6379/0
REDIS_SESSION_KEY_PREFIX=aura:sessions
SESSION_TTL_SECONDS=0

Use Redis mode for multi-instance or restart-resilient deployments.

Reliability Controls (Real Provider Mode)

In AURA_PROVIDER_MODE=real, Aura applies retries, exponential backoff, and a circuit breaker to UCP/BMS/AP2 HTTP calls.

HTTP_RETRY_ATTEMPTS=3
HTTP_RETRY_BACKOFF_SECONDS=0.2
CIRCUIT_BREAKER_FAILURE_THRESHOLD=3
CIRCUIT_BREAKER_RESET_SECONDS=30

AP2 settlement requests also include a deterministic Idempotency-Key derived from mandate data to reduce duplicate settlement risk on retries.

Observability

Aura now includes baseline observability primitives:

• Correlation ID propagation via X-Correlation-ID
• Structured request logs with correlation ID and latency
• In-memory metrics snapshot endpoint at GET /metrics

Quick check:

curl -i http://localhost:8080/health
curl http://localhost:8080/metrics

Streamlit Dashboard

streamlit run ui/dashboard.py

Opens at http://localhost:8501. Runs the full pipeline visually with real-time agent status cards, vendor tables, compliance badges, and settlement results. Works in demo mode (no GCP credentials needed) or API mode (calls the FastAPI server). See Dashboard Guide for details.

Run Tests

pytest tests/ -v

See Testing Guide for full test suite documentation.

---

Project Structure

aura/
├── main.py               # FastAPI app + ADK Runner
├── agents/
│   ├── architect.py      # Root orchestrator (SequentialAgent wiring)
│   ├── scout.py          # UCP vendor discovery
│   ├── sentinel.py       # KYC/AML compliance gate
│   └── closer.py         # AP2 payment settlement
├── tools/
│   ├── ucp_tools.py      # Universal Commerce Protocol mock
│   ├── compliance_tools.py  # BMS KYC/AML compliance mock
│   └── ap2_tools.py      # Agent Payments Protocol v2 mock
├── docs/
│   ├── ARCHITECTURE.md   # System architecture diagram
│   ├── AGENT_FLOW.md     # Sequence diagrams (happy + blocked path)
│   ├── DATA_MODEL.md     # Data model class diagram
│   ├── DEPLOYMENT.md     # Kagent deployment guide
│   └── PROTOCOLS.md      # UCP + AP2 protocol design rationale
├── tests/
│   ├── test_compliance_tool.py
│   └── test_flow.py
├── Dockerfile            # Multi-stage production container
├── scripts/
│   └── demo.sh           # Demo run script
├── deploy/
│   └── kagent.yaml       # Kagent v1alpha2 CRD manifests
└── requirements.txt

---

Documentation

For Business Users

Document	Description
Business Guide	What Aura does, business value, use cases, glossary — no code
Demo Script	Hackathon pitch guide, live demo steps, and judge Q&A prep
PRD	Full Product Requirements Document

For Technical Users

Document	Description
Technical Guide	Setup, agent internals, tool layer, extending Aura, production checklist
Architecture	System topology and component diagram
Agent Flow	Sequence diagrams for happy path and compliance block
Data Model	VendorEndpoint, IntentMandate, ComplianceResult schemas
API Reference	REST endpoints — /run, /run/stream, /health
Dashboard	Streamlit UI guide (demo & API modes)
Testing	Test suite coverage and how to run tests
Deployment	Kagent Kubernetes deployment guide
Protocols	UCP, AP2, and BMS protocol design rationale

---

GCP Configuration

Setting	Value
Project	ai-agent-labs-oslo-26-team-6
Region	us-central1
Model	gemini-2.5-flash via Vertex AI

---

License

Apache 2.0 — see LICENSE.