Agent Manifest Documentation

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: July 2026

Overview

This document describes the operational pipeline of the Agent Manifest ecosystem — the 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.

The Ambassador guides the user through composing the manifest. Conformance with the official specification is validated server-side: the Diplomat checks every submission against the canonical v1.0 JSON Schema before it is stored.

2. Diplomat — Registration API

Endpoint that receives, validates, and stores manifests.

The Diplomat acts as the structural validation gate for the public registry.

Response (accepted):

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

registry_updated is false at submission time: the registry index is rebuilt afterwards by the dataset repository’s automation, not within the API call.

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.

manifests/
  YYYY/
    MM/
      agent-id.json

Manifests are stored by year and month and retain full Git history.

4. Registry — Agent Index

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

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.

{
  "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"
}

The endpoint returns the registry location.

Full Registration Flow

Agent or User
     ↓
Ambassador (composes 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 Note
Spec v1.0 Published DOI: 10.5281/zenodo.18833956
Ambassador Operational  
Diplomat API Operational  
Dataset Public  
Registry generator Operational Rebuilt by GitHub Actions
Discovery endpoint Active  

Possible extensions

The following are directions under consideration. None is committed, dated, or promised; the governed direction of the project is recorded in ROADMAP.md.

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