Agent Trust Ledger — Autonomous AI Agent Escrow & Reputation Rail

Google Cloud Agentic AI Hackathon | Track: Fortified Enterprise Fleet

Deployed Cloud Run Service: https://agent-trust-ledger-1064660975371.us-central1.run.app
Google Cloud Project ID: massive-house-506806-t6 (Region: us-central1)
Gemini Engine: Vertex AI via Google ADK (gemini-3.5-flash)
Official A2A Agent Cards: Escrow Mediator | Buyer Agent | Vendor Agent

---

1. Architecture Overview & The Two Registry Layers

As autonomous AI agents procure, negotiate, and transact with one another, they require both an operational transaction mediator and an enterprise discovery catalog.

The Agent Trust Ledger implements two distinct registry layers:

1. Application Agent Registry (Firestore):

   • Operational runtime database storing agent identity, policy constraints (spend limits, approval thresholds), dynamic status (active, paused, suspended), and cross-session reputation records.
   • Manages stateful memory banks, append-only audit ledgers, and transaction holds.

2. Google Cloud Agent Registry:

   • Centralized official discovery and governance catalog within Google Cloud.
   • Indexes the three deployed A2A Agent Cards via declared Service resources for cross-organization agent discovery.

---

2. A2A Discovery Endpoints

The deployed Cloud Run service hosts three public Agent-to-Agent (A2A) discovery endpoints:

Agent Role	Discovery Endpoint	Official Service ID
Escrow Mediator	/.well-known/agent-card.json	escrow-mediator
Buyer Agent	/agents/buyer/.well-known/agent-card.json	buyer-agent
Vendor Agent	/agents/vendor/.well-known/agent-card.json	vendor-agent

---

3. Local Quickstart (Zero Cloud Credentials Needed)

All unit tests and local simulations run fully offline using in-memory fallbacks:

# 1. Clone & enter repository
cd devpost

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run all unit tests (43 unit tests covering cards, guardrails, governance)
python -m unittest discover tests

# 4. Start local development server
python dashboard/app.py

Open http://localhost:8080 in your browser.

---

4. Google Cloud Deployment (Windows PowerShell)

Step 1 — Authenticate, Set Project & Install Alpha Component

gcloud auth login
gcloud config set project massive-house-506806-t6

# Install Agent Registry alpha CLI component (Run PowerShell as Admin if needed)
gcloud components update
gcloud components install alpha
gcloud alpha agent-registry services create --help

Step 2 — Enable Required GCP APIs

gcloud services enable run.googleapis.com
gcloud services enable firestore.googleapis.com
gcloud services enable pubsub.googleapis.com
gcloud services enable cloudtrace.googleapis.com
gcloud services enable aiplatform.googleapis.com
gcloud services enable agentregistry.googleapis.com

Step 3 — Deploy to Cloud Run

.\scripts\deploy.ps1

The script builds the container with gunicorn, deploys to us-central1, retrieves the live URL, and validates all three agent-card endpoints.

Step 4 — Export Local Agent Cards

$env:CLOUD_RUN_SERVICE_URL = "https://agent-trust-ledger-1064660975371.us-central1.run.app"
python scripts/export_agent_cards.py --base-url $env:CLOUD_RUN_SERVICE_URL

This generates deployment/escrow-agent-card.json, deployment/buyer-agent-card.json, and deployment/vendor-agent-card.json containing the active service base URL.

Step 5 — Register Agents in Google Cloud Agent Registry

$env:GOOGLE_CLOUD_PROJECT = "massive-house-506806-t6"
$env:AGENT_REGISTRY_LOCATION = "us-central1"
.\scripts\register_agents.ps1

This runs the official Service creation commands:

gcloud alpha agent-registry services create escrow-mediator `
  --project=massive-house-506806-t6 `
  --location=us-central1 `
  --display-name="Agent Trust Ledger — Escrow Mediator" `
  --agent-spec-type=a2a-agent-card `
  --agent-spec-content="deployment/escrow-agent-card.json"

Service verification:

# List registered services
gcloud alpha agent-registry services list `
  --project=$env:GOOGLE_CLOUD_PROJECT `
  --location=$env:AGENT_REGISTRY_LOCATION

# List registered agents
gcloud alpha agent-registry agents list `
  --project=$env:GOOGLE_CLOUD_PROJECT `
  --location=$env:AGENT_REGISTRY_LOCATION

# Describe service
gcloud alpha agent-registry services describe escrow-mediator `
  --project=$env:GOOGLE_CLOUD_PROJECT `
  --location=$env:AGENT_REGISTRY_LOCATION

Step 6 — Verify Deployment & Discovery

.\scripts\verify_deployment.ps1 -ServiceUrl $env:CLOUD_RUN_SERVICE_URL

---

5. Configuration Reference

Variable	Description	Default / Example
GOOGLE_CLOUD_PROJECT	GCP Project ID	massive-house-506806-t6
GOOGLE_CLOUD_LOCATION	Primary GCP Region	us-central1
AGENT_REGISTRY_LOCATION	Agent Registry Region	us-central1
GEMINI_MODEL	Vertex AI Gemini model name	gemini-3.5-flash
CLOUD_RUN_SERVICE_URL	Deployed Cloud Run base URL	https://agent-trust-ledger-xxx.run.app
USE_FIRESTORE	Enable production Firestore backend	true (deployed) / false (local)
USE_PUBSUB	Enable production Google Cloud Pub/Sub	true (deployed) / false (local)
USE_CLOUD_TRACE	Enable OpenTelemetry Cloud Trace export	true (deployed) / false (local)
DEMO_MODE	Allow interactive dashboard actions	true
PORT	Web server listening port	8080

---

6. Required IAM Roles & Permissions

Developer / Deployer Account

• roles/run.admin — Deploy Cloud Run service
• roles/iam.serviceAccountUser — Attach service account to Cloud Run
• roles/serviceusage.serviceUsageAdmin — Enable required APIs
• roles/agentregistry.admin — Register and manage Agent Registry service entries

Cloud Run Runtime Service Account

• roles/datastore.user — Read and write Firestore operational collections
• roles/pubsub.publisher — Publish inter-agent event messages
• roles/pubsub.subscriber — Pull / receive pushed event messages
• roles/cloudtrace.agent — Export OpenTelemetry spans to Google Cloud Trace
• roles/aiplatform.user — Invoke Vertex AI Gemini models

---

7. Important Product & Security Disclosures

1. Simulated Escrow Funds / Demo Credits: All funds handled by this application are simulated balances (demo credits). No real currency or payment processing is executed.

2. Security & Trust Guard: Security & Trust Guard — custom pre-model security validation inspired by Model Armor principles. It runs deterministic HMAC signature verification, agent authorization checks, and prompt-injection pattern screening before any claim payload is evaluated by an LLM.

3. Agent Identity: Demonstration mode uses HMAC-SHA256 with key verification to demonstrate the cryptographic identity pattern. In enterprise production, this would be replaced with asymmetric Ed25519 key pairs per agent or Google Cloud Workload Identity Federation.

---

8. Troubleshooting

• Agent Card returns 404: Verify CLOUD_RUN_SERVICE_URL matches the deployed URL and routes in dashboard/app.py are active.
• Agent Registry API disabled: Run gcloud services enable agentregistry.googleapis.com --project=massive-house-506806-t6.
• Missing IAM permissions: Ensure your user has roles/agentregistry.admin and roles/run.admin.
• gcloud CLI command group: If gcloud alpha agent-registry is not recognized, run gcloud components update and gcloud components install alpha in an Administrator PowerShell session.
• Firestore / Pub/Sub fallback: App logs [FirestoreClient] Initialized: in-memory fallback mode when running without GCP credentials. When deployed, set USE_FIRESTORE=true and USE_PUBSUB=true.