# agent-network-protocol/agentnetworkprotocol architecture

> Architecture diagram of the GitHub repository agent-network-protocol/agentnetworkprotocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agent-network-protocol/agentnetworkprotocol
- Repository: https://github.com/agent-network-protocol/agentnetworkprotocol

## Overview

##### Project type and purpose
- This is an open-source protocol specification and documentation project (AgentNetworkProtocol, ANP). Its goal is to define a three-layer communication protocol for “intelligent agents,” analogous to how HTTP works for web browsers. It provides specifications, design papers, sample programs, and SDK references rather than a monolithic application.

##### File structure
- Top-level directories:
- specs at root (e.g., “01-agentnetworkprotocol-technical-white-paper.md”, “03-did-wba-method-design-specification.md”, etc.)
- docs/ – getting-started guides, tutorials, Chinese translations
- examples/ – ADP (Application Description Protocol) sample payloads and APIs
- blogs/ & chinese/ – community articles and thought pieces
- scripts/ – small utilities for repository maintenance
- Patterns:
- Layered protocol docs (identity, meta-protocol, application protocol)
- Multilingual support (English/Chinese)
- Sample payloads for concrete application protocols under examples/adp

##### README for additional insights
- The project defines a “Three-Layer Protocol Architecture”:
a. Identity & Secure Communication Layer (W3C DID, encryption)
b. Meta-Protocol Layer (negotiation of communication protocols)
c. Application Protocol Layer (semantic descriptions, discovery, application-domain protocols)
- Quick-start and SDK implementation are in a separate repo (AgentConnect).

a. Main components
- Agent Nodes: represent any intelligent agent instance.
- DID Registry / Decentralized Identity Service: issues/verifies DIDs.
- Secure Communication Channel: end-to-end encryption (based on DID).
- Meta-Protocol Negotiator: handles protocol negotiation between agents.
- Application Protocol Manager: hosts one or more domain protocols (e.g., ADP hotel booking).
- External Services (optional): e.g., DID resolution endpoints, semantic-web services.
- SDK / AgentConnect Implementation: code library that realizes these protocols.
b. Relationships & interactions
1. Agent A queries DID Registry to resolve Agent B’s DID.
2. Agents establish a secure channel (encrypt/decrypt) via the Identity layer.
3. Through that channel, they use the Meta-Protocol layer to negotiate which application protocol to use.
4. Once agreed, they exchange domain-specific messages (e.g., ADP hotel search) via the Application layer.
c. Architectural patterns & design principles
- Layered architecture: each layer builds on lower ones; they can evolve independently.
- Protocol composition: modular, extensible by adding new application protocols.
- Decentralization: uses W3C DID standard, no single point of authority.
- Semantic interoperability: uses JSON-LD or YAML for interface descriptions.
d. Relevant technologies / frameworks
- W3C DID for identity.
- JSON-LD / YAML for metadata and API descriptions.
- Transport over HTTP or any bi-directional channel.
- Encryption primitives (e.g., X25519, AES-GCM).
- Semantic Web specifications (for discovery & description).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Agents
    subgraph "Agents"
        A["Agent A"]:::agent
        B["Agent B"]:::agent
    end

    %% Identity & Secure Communication Layer
    subgraph "Identity & Secure Communication Layer"
        DIDRegistry["DID Registry / Decentralized Identity Service"]:::identity
        E2E["End-to-End Encrypted Communication Protocol"]:::identity
        MSG["DID Message Service Protocol"]:::identity
    end

    %% Meta-Protocol Layer
    subgraph "Meta-Protocol Layer"
        MetaNegotiator["Meta-Protocol Negotiator"]:::meta
    end

    %% Application Protocol Layer
    subgraph "Application Protocol Layer"
        AppManager["Application Protocol Manager"]:::app
        subgraph "Sample App Protocols"
            ADPHotel["ADP Hotel Booking Protocol"]:::app
            ADPLkCoffee["ADP Coffee Purchase Protocol"]:::app
        end
    end

    %% External & SDK
    subgraph "External Services / SDK"
        SDK["AgentConnect SDK"]:::external
        Semantic["Semantic-Web Services"]:::external
    end

    %% Documentation & Examples
    subgraph "Docs & Examples"
        Specs["Protocol Specs (specs/)"]:::docs
        DocsDir["Guides & Tutorials (docs/)"]:::docs
        Examples["Sample Payloads (examples/)"]:::docs
    end

    %% Flows
    A -->|"DID Resolve"| DIDRegistry
    B -->|"DID Resolve"| DIDRegistry

    DIDRegistry -->|"Resolve DID"| E2E
    E2E -->|"Secure Channel"| MSG
    MSG -->|"Negotiate Protocol"| MetaNegotiator
    MetaNegotiator -->|"Select App Protocol"| AppManager
    AppManager -->|"ADP: hotel search"| ADPHotel
    AppManager -->|"ADP: coffee purchase"| ADPLkCoffee

    A -->|"Uses"| SDK
    B -->|"Uses"| SDK
    AppManager -->|"Semantic Discovery"| Semantic

    %% Click Events - Identity Layer
    click DIDRegistry "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/specs/03-did-wba-method-design-specification.md"
    click E2E "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/message/04-end-to-end-encrypted-communication-technology-protocol-based-on-did.md"
    click MSG "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/message/05-message-service-protocol-based-on-did.md"

    %% Click Events - Identity Translations & Tests
    click E2E "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/message/04-基于did的端到端加密通信技术协议.md"
    click MSG "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/message/05-基于did的消息服务协议.md"
    click DIDRegistry "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/docs/did-wba-server-test-interface.md"
    click DIDRegistry "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/references/did_web-method-specification.html"

    %% Click Events - Meta-Protocol Layer
    click MetaNegotiator "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/specs/06-anp-agent-communication-meta-protocol-specification.md"
    click MetaNegotiator "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/docs/how-anp-based-webagent-works.md"
    click MetaNegotiator "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/06-ANP-智能体通信元协议规范.md"

    %% Click Events - Application Protocol Layer
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/specs/07-anp-agent-description-protocol-specification.md"
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/specs/08-ANP-Agent-Discovery-Protocol-Specification.md"
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/specs/09-anp-peer-to-peer-agent-transaction-specification.md"
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/07-ANP-智能体描述协议规范.md"
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/08-ANP-智能体发现协议规范.md"
    click AppManager "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/chinese/09-ANP-智能体点对点交易规范.md"

    %% Click Events - Sample Application Protocols
    click ADPHotel "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/hotel/examples/ad.json"
    click ADPHotel "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/hotel/examples/api/search-interface.yaml"
    click ADPHotel "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/hotel/examples/api/nl-interface.yaml"
    click ADPHotel "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/hotel/examples/api/booking-interface.yaml"
    click ADPHotel "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/hotel/examples/hotel_room.json"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/ad.json"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/api/nl-interface.yaml"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/api/purchase-interface.yaml"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/orange-americano/orange-americano.json"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/roasted-coconut-latte/roasted-coconut-latte.json"
    click ADPLkCoffee "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/examples/adp/lkcoffe/silk-latte/silk-latte.json"

    %% Click Events - SDK & Quickstart
    click SDK "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/README.md"
    click SDK "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/README.cn.md"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/docs/anp-getting-started-guide.md"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/docs/chinese/ANP入门指南.md"

    %% Click Events - Docs & Examples Directories
    click Specs "https://github.com/agent-network-protocol/agentnetworkprotocol/tree/main/specs/"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/tree/main/docs/"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/tree/main/docs/chinese/"
    click Examples "https://github.com/agent-network-protocol/agentnetworkprotocol/tree/main/examples/"

    %% Scripts
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/scripts/add_copyright.py"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/scripts/rename_images.py"
    click DocsDir "https://github.com/agent-network-protocol/agentnetworkprotocol/blob/main/scripts/replace_spaces_with_hyphens.py"

    %% Styles
    classDef identity fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef meta fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef app fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef external fill:#E0E0E0,stroke:#424242,color:#424242
    classDef agent fill:#F5F5F5,stroke:#616161,color:#616161
    classDef docs fill:#FFF9C4,stroke:#F57F17,color:#F57F17
```
