Agent Manifest

Operational Architecture

This document describes the operational infrastructure of the Agent Manifest ecosystem. It complements the conceptual architecture described in the main README.

---

Agent Manifest — Operational Infrastructure
Status: Operational · Version: 1.0 · Updated: March 2026

---

Overview

This document describes the operational pipeline of the Agent Manifest ecosystem — the real infrastructure flow from manifest generation to public discovery.

The system is composed of five components that form a continuous, auditable public registration pipeline.

---

Pipeline

The operational pipeline is append-only and publicly auditable:

Ambassador → Diplomat → Dataset → Registry → Discovery

---

Components

1. Ambassador — Manifest Generator

Public interface for creating Agent Manifest declarations.

• URL: agent-manifest.github.io/agent-manifest-ambassador
• Input: five structured questions
• Output: valid Agent Manifest v1.0 JSON Schema: agent-manifest-spec.org/spec/v1.0/schema.json

The Ambassador ensures that every manifest conforms to the official specification before submission.

---

2. Diplomat — Registration API

Endpoint that receives, validates, and stores manifests.

• Endpoint: POST https://agent-manifest-diplomat.vercel.app/api/register
• Validates: manifest_version, agent_id, required fields
• On success: writes manifest to the public dataset
• On failure: returns structured error with rejection reason

The Diplomat acts as the integrity gatekeeper for the public registry.

Response (accepted):

{
  "status": "accepted",
  "agent_id": "example-agent",
  "stored_at": "manifests/2026/03/example-agent.json",
  "registry_updated": true
}

Response (rejected):

{
  "status": "rejected",
  "errors": ["manifest_version must be '1.0'"]
}

---

3. Dataset — Public Manifest Storage

All accepted manifests are stored in a public repository.

• Repository: agent-manifest-dataset
• Structure:

manifests/
  YYYY/
    MM/
      agent-id.json

This structure provides transparency, version history, and public auditability for every registered agent.

---

4. Registry — Agent Index

A registry file lists all registered agents and is automatically rebuilt on every new manifest commit.

• File: registry.json (root of dataset repository)
• Generated by: GitHub Actions on push to manifests/

Each entry contains:

{
  "agent_id": "example-agent",
  "agent_name": "Example Agent",
  "manifest_url": "https://raw.githubusercontent.com/agent-manifest/agent-manifest-dataset/main/manifests/2026/03/example-agent.json",
  "registered_at": "2026-03-14"
}

---

5. Discovery Endpoint — Network Entry Point

The registry is discoverable via a standard .well-known path.

• URL: https://agent-manifest-spec.org/.well-known/agent-manifest-registry.json

{
  "registry_type": "agent-manifest-public-registry",
  "registry_version": "1.0",
  "registry_name": "Agent Manifest Public Registry",
  "registry_url": "https://raw.githubusercontent.com/agent-manifest/agent-manifest-dataset/main/registry.json",
  "dataset_repository": "https://github.com/agent-manifest/agent-manifest-dataset",
  "specification_repository": "https://github.com/agent-manifest/agent-manifest"
}

Any system can locate the registry by reading this endpoint — no prior configuration required.

---

Full Registration Flow

Agent or User
     ↓
Ambassador (generates valid manifest)
     ↓
Diplomat API (validates + stores)
     ↓
Dataset Repository (public manifest storage)
     ↓
GitHub Actions (rebuilds registry.json)
     ↓
Discovery Endpoint (.well-known)

---

Design Principles

Principle	Implementation
Minimalism	Only essential components; no unnecessary dependencies
Transparency	All manifests are public and permanently auditable
Append-only infrastructure	Manifests are never overwritten; new entries extend the registry
Declarative identity	Agents explicitly declare scope before interaction
Interoperability	Standard JSON, open schema, public endpoints

---

Current Status

Component	Status
Spec v1.0	Published — DOI: 10.5281/zenodo.18833956
Ambassador	Operational
Diplomat API	Operational
Dataset	Public
Registry generator	Automated via GitHub Actions
Discovery endpoint	Active

---

Future Extensions

• GET /agents/{agent_id} — direct agent lookup by ID
• /.well-known/agent-manifest.json — domain-level agent identity publication
• Search by capability or autonomy level
• Federated registries

---

Agent Manifest · agent-manifest-spec.org · CC BY 4.0 · Hernán Alfredo Capucci · ORCID: 0009-0008-7216-3032

This site is open source. Improve this page.