Project Overview

Project Overview

**Referenced Files in This Document** - [agentid_build_plan.md](https://github.com/RunTimeAdmin/AgentID/blob/main/agentid_build_plan.md) - [backend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/package.json) - [frontend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/package.json) - [backend/src/config/index.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/config/index.js) - [backend/src/models/db.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/db.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.js) - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/saidBinding.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/saidBinding.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.js) - [backend/src/services/bagsReputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsReputation.js) - [backend/src/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [backend/src/routes/register.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/register.js) - [backend/src/routes/verify.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/verify.js) - [backend/src/routes/badge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/badge.js) - [frontend/src/components/TrustBadge.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/components/TrustBadge.jsx) - [frontend/src/widget/Widget.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/widget/Widget.jsx)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

AgentID is the Bags-native trust layer for AI agents. It provides a trust verification layer that:

• Wraps Bags' Ed25519 agent authentication flow to establish wallet ownership
• Binds agent identities to the Solana Agent Registry (SAID Protocol)
• Adds Bags-specific reputation scoring
• Surfaces a human-readable trust badge inside Bags chat and embeddable widgets

AgentID's value is rooted in PKI challenge-response spoofing prevention using Ed25519, ensuring that only agents who truly control the private key can operate.

Target audience:

• Every one of the 48 AI Agent projects participating in the hackathon
• Every Bags user interacting with agents
• Developers building on Bags who want their agents to display a trust badge

Core value proposition:

• First Bags-native binding layer connecting SAID with the Bags ecosystem
• PKI challenge-response prevents spoofing and enables runtime verification
• Human-readable trust indicators and embeddable badges for transparency

Project Structure

The repository is organized into a backend API service and a frontend UI and widget system:

• Backend: Node.js/Express API with routes, services, models, and middleware
• Frontend: React-based registry UI and embeddable widget

graph TB
subgraph "Backend"
CFG["Config<br/>environment variables"]
DB["PostgreSQL<br/>agent_identities, agent_verifications, agent_flags"]
SRV["Services<br/>bagsAuthVerifier, saidBinding, pkiChallenge, bagsReputation, badgeBuilder"]
ROUTES["Routes<br/>register, verify, badge, reputation"]
end
subgraph "Frontend"
UI["Registry UI<br/>pages, components"]
WIDGET["Widget<br/>embeddable HTML/SVG"]
end
CFG --> ROUTES
ROUTES --> SRV
SRV --> DB
UI --> ROUTES
WIDGET --> ROUTES

Loading

Core Components

• Bags Auth Wrapper: Validates wallet ownership via Bags Ed25519 challenge-response
• SAID Binding: Registers or verifies agents in the SAID Identity Gateway
• PKI Challenge-Response: Ongoing verification using Ed25519 challenge messages
• Bags Reputation Scoring: Computes a 0-100 score using five factors
• Trust Badge: Human-readable badge JSON, SVG, and embeddable widget

Architecture Overview

AgentID sits between Bags agents and the applications/users interacting with them. It integrates with Bags API for authentication and analytics, with SAID for trust scores and A2A discovery, and exposes a trust badge and verification endpoints.

graph TB
subgraph "External Systems"
BAGS["Bags API<br/>/agent/v2/auth/*, /analytics/*"]
SAID["SAID Identity Gateway<br/>/agents/register, /agents/:pubkey, /discover"]
end
subgraph "AgentID Backend"
R["Routes<br/>/register, /verify/*, /badge/*, /reputation/*"]
S_BAGS["Service: bagsAuthVerifier"]
S_SAID["Service: saidBinding"]
S_PKI["Service: pkiChallenge"]
S_REP["Service: bagsReputation"]
S_BADGE["Service: badgeBuilder"]
Q["Queries<br/>DB access"]
DB["PostgreSQL"]
end
subgraph "AgentID Frontend"
UI["Registry UI"]
W["Widget"]
end
BAGS <- --> S_BAGS
SAID <- --> S_SAID
R --> S_BAGS
R --> S_SAID
R --> S_PKI
R --> S_REP
R --> S_BADGE
S_BAGS --> Q
S_SAID --> Q
S_PKI --> Q
S_REP --> Q
S_BADGE --> Q
Q --> DB
UI --> R
W --> R

Loading

Detailed Component Analysis

Registration and Wallet Ownership Verification

AgentID's registration flow wraps Bags' Ed25519 auth to verify wallet ownership.

PKI Challenge-Response Spoofing Prevention

AgentID issues time-bound challenges and verifies Ed25519 signatures to prevent spoofing.

SAID Protocol Binding

AgentID registers or retrieves agent trust data from SAID and augments it with Bags-specific metadata.

Bags Ecosystem Reputation Scoring

AgentID computes a 0-100 score combining fee activity, success rate, registration age, SAID trust score, and community verification.

Trust Badge API and Widget

AgentID exposes badge JSON, SVG badge, and HTML widget endpoints.

Dependency Analysis

AgentID's backend depends on:

• External APIs: Bags API, SAID Identity Gateway
• Internal services: Ed25519 verification, SAID binding, PKI challenge-response
• Data stores: PostgreSQL, Redis

Performance Considerations

• Caching: Badge JSON cached with configurable TTL
• Rate limiting: Authentication endpoints use rate limits
• Database indexing: JSONB fields for capability sets
• Asynchronous operations: SAID binding is non-blocking

Troubleshooting Guide

Common issues:

• Registration failures due to invalid signature
• SAID registration unavailable
• Verification errors (nonce expired)
• Badge not found

Conclusion

AgentID delivers a Bags-native trust layer that wraps Bags Ed25519 auth, binds agents to SAID, adds Bags-specific reputation scoring, provides human-readable trust badges, and prevents spoofing via PKI challenge-response.