



Independent Submission                                           J. Song
Internet-Draft                                                     HKUST
Intended status: Experimental                                    M. Yuan
Expires: 26 September 2026                                          CUHK
                                                           25 March 2026


                     Agent Internet Protocol (AIP)
                         draft-song-anp-aip-00

Abstract

   The Internet Protocol (IP, RFC 791) provides best-effort datagram
   delivery between hosts identified by numeric addresses.  The Agent
   Internet Protocol (AIP) provides best-effort datagram delivery
   between autonomous AI agents identified by agent:// URIs -- human-
   readable, capability-descriptive names.

   AIP is designed to serve as the narrow waist of the Agent Network
   Protocol (ANP) suite, occupying an architectural position analogous
   to IP in the TCP/IP suite: a minimal common substrate through which
   upper-layer protocols and link technologies interoperate without
   direct coupling.

   This document specifies the AIP message format, addressing model,
   upper-layer protocol demultiplexing, TLV options, message processing
   rules, error handling, and interfaces to adjacent protocol layers.
   Name registration, distributed name resolution, and semantic
   discovery are provided by a companion resolver service and are
   outside the scope of this document.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 26 September 2026.




Song & Yuan             Expires 26 September 2026               [Page 1]

Internet-Draft                     AIP                        March 2026


Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Problem Statement . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Assumptions . . . . . . . . . . . . . . . . . . . . . . .   5
     1.4.  Requirements Language . . . . . . . . . . . . . . . . . .   5
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   5
   3.  The agent:// URI Scheme . . . . . . . . . . . . . . . . . . .   6
     3.1.  Syntax  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     3.2.  Comparison Rules  . . . . . . . . . . . . . . . . . . . .   7
     3.3.  Wire Encoding . . . . . . . . . . . . . . . . . . . . . .   7
     3.4.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .   8
     3.5.  Design Rationale  . . . . . . . . . . . . . . . . . . . .   8
   4.  AIP Message Format  . . . . . . . . . . . . . . . . . . . . .   9
     4.1.  Header Structure  . . . . . . . . . . . . . . . . . . . .   9
     4.2.  Field Definitions . . . . . . . . . . . . . . . . . . . .   9
     4.3.  TLV Options . . . . . . . . . . . . . . . . . . . . . . .  13
     4.4.  Message Signature . . . . . . . . . . . . . . . . . . . .  15
   5.  Local Resolver  . . . . . . . . . . . . . . . . . . . . . . .  15
     5.1.  Resolver Interface  . . . . . . . . . . . . . . . . . . .  15
     5.2.  Optional Semantic Resolver Extension  . . . . . . . . . .  16
     5.3.  Requirements on Implementations . . . . . . . . . . . . .  16
   6.  Name Resolution . . . . . . . . . . . . . . . . . . . . . . .  16
     6.1.  Exact Resolution (SEM flag clear) . . . . . . . . . . . .  17
     6.2.  Semantic Resolution (SEM flag set) -- Optional
           Extension . . . . . . . . . . . . . . . . . . . . . . . .  17
   7.  Message Processing  . . . . . . . . . . . . . . . . . . . . .  18
     7.1.  Sending . . . . . . . . . . . . . . . . . . . . . . . . .  18
     7.2.  Receiving . . . . . . . . . . . . . . . . . . . . . . . .  18
     7.3.  Error Handling  . . . . . . . . . . . . . . . . . . . . .  19
     7.4.  Deduplication . . . . . . . . . . . . . . . . . . . . . .  20
     7.5.  Rate Limiting . . . . . . . . . . . . . . . . . . . . . .  21
   8.  Interfaces  . . . . . . . . . . . . . . . . . . . . . . . . .  21
     8.1.  Upper Layer Interface (AITP and others) . . . . . . . . .  21
     8.2.  Lower Layer Interface (Link Layer)  . . . . . . . . . . .  21
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  22



Song & Yuan             Expires 26 September 2026               [Page 2]

Internet-Draft                     AIP                        March 2026


     9.1.  Message Authentication  . . . . . . . . . . . . . . . . .  22
     9.2.  Identity and Signing Key Relationship . . . . . . . . . .  22
     9.3.  Name Spoofing . . . . . . . . . . . . . . . . . . . . . .  22
     9.4.  Resolution Poisoning  . . . . . . . . . . . . . . . . . .  23
     9.5.  Replay Attacks  . . . . . . . . . . . . . . . . . . . . .  23
     9.6.  Resource Exhaustion . . . . . . . . . . . . . . . . . . .  23
     9.7.  Semantic Resolution Gaming  . . . . . . . . . . . . . . .  23
     9.8.  Privacy . . . . . . . . . . . . . . . . . . . . . . . . .  24
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  24
     10.1.  URI Scheme Registration: agent . . . . . . . . . . . . .  24
     10.2.  AIP Message Type Registry  . . . . . . . . . . . . . . .  24
     10.3.  AIP Protocol Number Registry . . . . . . . . . . . . . .  24
     10.4.  AIP Error Code Registry  . . . . . . . . . . . . . . . .  24
     10.5.  AIP Flag Bits Registry . . . . . . . . . . . . . . . . .  25
     10.6.  AIP Option Type Registry . . . . . . . . . . . . . . . .  25
   11. Implementation Status . . . . . . . . . . . . . . . . . . . .  25
     11.1.  ClawNet  . . . . . . . . . . . . . . . . . . . . . . . .  25
   12. References  . . . . . . . . . . . . . . . . . . . . . . . . .  26
     12.1.  Normative References . . . . . . . . . . . . . . . . . .  26
     12.2.  Informative References . . . . . . . . . . . . . . . . .  26
   Appendix A.  Example Resolver Scoring (Informative) . . . . . . .  27
   Appendix B.  Network Bootstrap (Informative)  . . . . . . . . . .  29
     B.1.  Bootstrap Sequence  . . . . . . . . . . . . . . . . . . .  29
     B.2.  Minimal Bootstrap . . . . . . . . . . . . . . . . . . . .  30
   Appendix C.  Implementation Alignment Notes . . . . . . . . . . .  30
   Appendix D.  AIP in Isolation (Informative) . . . . . . . . . . .  31
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  32

1.  Introduction

1.1.  Problem Statement

   The Internet Protocol [RFC0791] provides a universal mechanism for
   delivering datagrams between hosts identified by fixed-length numeric
   addresses.  IP was designed under the assumption that communication
   endpoints are hardware devices with stable locations on physical
   networks.

   In agent networking, the endpoints are not hardware devices but
   software agents: autonomous programs that can be created, destroyed,
   migrated, and replicated at will.  They do not have fixed locations.
   They are identified not by physical attachment points but by their
   names and capabilities.








Song & Yuan             Expires 26 September 2026               [Page 3]

Internet-Draft                     AIP                        March 2026


   An AI agent that needs a French-to-Japanese translator does not know
   -- and should not need to know -- any IP address.  It needs to reach
   "agent://translation/fr-ja".  In AIP, names serve as addresses:
   rather than resolving a name to a numeric location before sending,
   the agent addresses messages directly to a human-readable URI and
   relies on a local resolver to map that name to a reachable peer.

   Current naming systems such as the Domain Name System [RFC1035] map
   human-readable names to network locations.  Agents need a naming
   system that maps intents to capabilities.  AIP provides the datagram
   substrate: name-based addressing with the agent:// URI scheme and
   best-effort message delivery.  The name resolution service itself --
   including registration, distributed lookup, and semantic search -- is
   provided by a companion resolver that runs above AIP as an upper-
   layer protocol (one such resolver is ANS [I-D.song-anp-ans]).

1.2.  Scope

   This document is one of four core Internet-Drafts in the Agent
   Network Protocol (ANP) suite: AIP (this document, datagram delivery),
   AITP [I-D.song-anp-aitp] (invocation transport), ANS
   [I-D.song-anp-ans] (name system), and ADP [I-D.song-anp-adp]
   (description and discovery).  The four drafts are designed to co-
   evolve as a self-contained protocol suite; no additional
   specification is required for baseline interoperability.  AIP's
   local-resolver semantic extension (Section 6.2) MAY be backed by an
   implementation that consults ADP discovery services for ranked
   capability matching; ANS core provides name-to-peer binding but does
   not itself perform ranked semantic discovery.

   AIP defines an experimental datagram protocol serving as the narrow
   waist of the ANP suite, analogous to IP in TCP/IP.  It provides a
   best-effort datagram service between named agents.

   AIP provides:

   1.  Name-based addressing using agent:// URIs.

   2.  Best-effort datagram delivery.

   3.  Upper-layer protocol demultiplexing via the Protocol field.

   4.  TTL-bounded relay with deduplication.

   5.  Extensible TLV options for timestamps, tracing, and priority.

   6.  Error reporting for undeliverable messages.




Song & Yuan             Expires 26 September 2026               [Page 4]

Internet-Draft                     AIP                        March 2026


   AIP does NOT provide:

   1.  Reliable delivery -- datagrams may be lost, duplicated, or
       reordered.  Reliability is the responsibility of a higher-layer
       protocol such as AITP [I-D.song-anp-aitp].

   2.  Ordering or flow control -- these are higher-layer functions.

   3.  Name registration, distributed lookup, or semantic discovery --
       AIP does not define these functions.  They are expected to be
       provided by a companion naming service; ANS [I-D.song-anp-ans] is
       one such architecture.

   4.  Fragmentation -- messages exceeding the link MTU are rejected,
       not fragmented.

   5.  Payload confidentiality -- encryption is the responsibility of a
       higher-layer protocol or the application.

1.3.  Assumptions

   AIP assumes:

   1.  A local resolver service capable of mapping agent:// URI tokens
       to link-layer delivery targets.  AIP does not require any
       specific resolver architecture.

   2.  A link layer that can deliver variable-length byte sequences
       between peers identified by peer ID.

   3.  AIP MAY be used with higher-layer protocols that provide
       reliability, ordering, or application semantics, but does not
       depend on them for baseline datagram operation.

1.4.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Terminology

   Agent  An autonomous software entity that participates in the ANP
      network.  An agent has a cryptographic identity (an Ed25519 key
      pair) and registers one or more agent:// URIs.




Song & Yuan             Expires 26 September 2026               [Page 5]

Internet-Draft                     AIP                        March 2026


   Name  The identifier component of an agent:// URI that appears after
      the optional namespace and slash.  For example, in "agent://acme/
      code-reviewer", the name is "code-reviewer".

   Namespace  An optional organizational prefix in an agent:// URI that
      groups related agents.  For example, in "agent://acme/code-
      reviewer", the namespace is "acme".  A URI without a namespace is
      in the global namespace.

   Resolution  The process of mapping an agent:// URI to a peer ID so
      that AIP can transmit a message.  Resolution is performed by a
      local resolver.

   Resolver  A local service that maps agent:// URIs to peer IDs.  AIP
      delegates all resolution to the resolver.  A resolver MAY
      additionally support semantic queries (see Section 6.2).

   AIP Message  The protocol data unit of AIP.  An independent, self-
      contained datagram carrying a fixed header, source and destination
      agent:// URIs, optional TLV options, and a payload.

   Peer ID  A globally unique identifier for a network participant,
      derived from its Ed25519 public key.  Used at the link layer for
      point-to-point addressing.

   Node  A machine (physical or virtual) running one AIP module.  A node
      has one peer ID.  Multiple agents MAY run on a single node.

   In summary: a node has one link-layer Peer ID; one or more agents MAY
   run on that node; AIP addresses agents by agent:// URI, not by Peer
   ID.

3.  The agent:// URI Scheme

   The agent:// URI is the fundamental addressing primitive of AIP.  It
   identifies an agent by a human-readable, capability-descriptive name
   rather than by a numeric network address.  The scheme is registered
   with IANA in accordance with [RFC7595] (see Section 10.1).

   An agent:// URI is a *routing token* designating a capability
   endpoint; it does not necessarily correspond to a singular legal
   identity.  Multiple agents, instances, or replicas MAY be reachable
   through the same URI via resolver-level load balancing or failover.
   Conversely, a single agent MAY register multiple URIs for different
   capabilities.






Song & Yuan             Expires 26 September 2026               [Page 6]

Internet-Draft                     AIP                        March 2026


3.1.  Syntax

   The syntax of agent:// URIs is defined in ABNF [RFC5234], following
   the generic URI structure of [RFC3986]:

   agent-uri    = "agent://" agent-path
   agent-path   = [ namespace "/" ] name [ "@" version ]
   namespace    = ident
   name         = ident
   ident        = LCALPHA-DIGIT *( LCALPHA-DIGIT / "-" )
   version      = 1*( DIGIT / "." / "-" / ALPHA )
   LCALPHA-DIGIT = %x61-7A / DIGIT    ; a-z / 0-9

   Names and namespaces MUST begin with a lowercase letter or digit,
   MUST NOT end with a hyphen, and MUST be at least one character long.
   Uppercase letters are not permitted; implementations MUST reject URIs
   containing uppercase letters rather than silently normalizing them.

   The total URI length (including the "agent://" prefix) MUST NOT
   exceed 263 octets (255 for the wire-encoded path plus 8 for the
   "agent://" prefix).

3.2.  Comparison Rules

   Because all characters in agent:// URIs are already constrained to
   lowercase, comparison is a simple octet-by-octet match of the wire-
   encoded forms after the following normalization:

   1.  Remove any trailing slash.

   2.  Remove any trailing "@" not followed by a version string.

   No percent-decoding is performed because the agent:// scheme does not
   permit percent-encoded characters.

3.3.  Wire Encoding

   On the wire, agent:// URIs are encoded WITHOUT the "agent://" prefix.
   The prefix is implicit -- all addresses in AIP messages are agent://
   URIs.  The encoding is UTF-8.

   The encoding function strips the 8-octet "agent://" prefix:

   *  wire_encode("agent://acme/translator") -> "acme/translator" (15
      octets)

   *  wire_encode("agent://translator") -> "translator" (10 octets)




Song & Yuan             Expires 26 September 2026               [Page 7]

Internet-Draft                     AIP                        March 2026


   *  wire_encode("agent://x/y@1.0") -> "x/y@1.0" (7 octets)

   The decoding function prepends "agent://":

   *  wire_decode("acme/translator") -> "agent://acme/translator"

   This avoids repeating the scheme prefix for both source and
   destination addresses on the wire.

3.4.  Examples

   Valid agent:// URIs:

   *  agent://translator -- global namespace, name only

   *  agent://acme/code-reviewer@2.1 -- namespace "acme", name "code-
      reviewer", version "2.1"

   *  agent://openai/gpt-assistant -- namespace "openai", name "gpt-
      assistant"

   *  agent://research/arxiv-search -- namespace "research", name
      "arxiv-search"

3.5.  Design Rationale

   A dedicated URI scheme is used rather than an existing scheme because
   agent:// URIs serve as first-class routing tokens, not as locators
   that resolve to network endpoints.  Existing alternatives were
   considered and found insufficient:

   *  DID URIs (did:method:...) are identity-centric and lack a built-in
      namespace/version structure for capability addressing.

   *  HTTPS well-known paths (https://host/.well-known/agent/...) couple
      agent identity to DNS names and TLS certificates, reintroducing
      the topology-bound addressing that AIP avoids.

   *  Opaque identifiers with external resolvers provide no human-
      readable semantics and require mandatory resolver infrastructure
      before any message can be sent.

   The agent:// scheme provides compact, human-readable routing tokens
   with a fixed wire encoding convention (Section 3.3).







Song & Yuan             Expires 26 September 2026               [Page 8]

Internet-Draft                     AIP                        March 2026


4.  AIP Message Format

   AIP messages are carried as payloads of link-layer frames.  An AIP
   message consists of a 16-octet fixed header, a variable-length
   address block containing the source and destination URIs (padded to a
   4-octet boundary), a variable-length TLV options region, and a
   variable-length payload.

4.1.  Header Structure

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Version|  Type |   Protocol    |  TTL  | Flags |   Reserved    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Message ID                            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       Payload Length                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Src URI Len |   Dst URI Len |        Options Length         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Source URI (wire-encoded, variable)    ...             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Destination URI (wire-encoded, variable) ...          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Address Padding (to 4-octet boundary)                 |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Options (TLV, padded to 4-octet boundary) ...         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Payload (variable)    ...                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Note: one tick mark represents one bit position.

               Figure 1: AIP Message Header (16 octets fixed)

4.2.  Field Definitions

   Version (4 bits)  Protocol version.  The current version is 1.
      Implementations MUST silently discard messages with an
      unrecognized version.

   Type (4 bits)  The message type:








Song & Yuan             Expires 26 September 2026               [Page 9]

Internet-Draft                     AIP                        March 2026


             +=======+=======+==================================+
             | Value | Name  | Description                      |
             +=======+=======+==================================+
             | 0     | DATA  | Normal data message (payload     |
             |       |       | delivery to upper layer).        |
             +-------+-------+----------------------------------+
             | 1     | ERROR | Error report (carries an error   |
             |       |       | payload, see Section 7.3).       |
             +-------+-------+----------------------------------+
             | 2     | PING  | Liveness probe.  Recipient MUST  |
             |       |       | reply with PONG.                 |
             +-------+-------+----------------------------------+
             | 3     | PONG  | Liveness reply.  Carries the     |
             |       |       | Message ID of the original PING. |
             +-------+-------+----------------------------------+
             | 4-15  |       | Reserved for future use.         |
             +-------+-------+----------------------------------+

                          Table 1: AIP Message Types

      Implementations MUST silently discard messages with unrecognized
      Type values.

   Protocol (8 bits)  Identifies the upper-layer protocol that will
      process the payload.  This field is analogous to the Protocol
      field in IPv4 [RFC0791].  It enables AIP to demultiplex incoming
      messages to the correct upper-layer handler.
























Song & Yuan             Expires 26 September 2026              [Page 10]

Internet-Draft                     AIP                        March 2026


             +=======+======+==================================+
             | Value | Name | Description                      |
             +=======+======+==================================+
             | 0     | NONE | No upper-layer protocol (used    |
             |       |      | for PING/PONG/control messages). |
             +-------+------+----------------------------------+
             | 1     | AITP | Agent Invocation Transport       |
             |       |      | Protocol [I-D.song-anp-aitp].    |
             +-------+------+----------------------------------+
             | 2     | ANS  | Agent Name System                |
             |       |      | [I-D.song-anp-ans].              |
             +-------+------+----------------------------------+
             | 3     | ADP  | Agent Description Protocol       |
             |       |      | [I-D.song-anp-adp].              |
             +-------+------+----------------------------------+
             | 4-254 |      | Available for future assignment  |
             |       |      | (IANA registry).                 |
             +-------+------+----------------------------------+
             | 255   | EXPT | Experimental / private use.      |
             +-------+------+----------------------------------+

                        Table 2: AIP Protocol Numbers

      The Type and Protocol fields serve orthogonal purposes.  Type
      identifies AIP's own control semantics (data delivery, error
      reporting, liveness probing).  Protocol identifies which upper-
      layer consumer processes the payload.  Thus, PING/PONG are AIP-
      layer operations (Type) that carry no upper-layer payload, while
      AITP, ANS, and ADP are upper- layer consumers (Protocol) whose
      payloads travel inside DATA messages (Type = 0).

      In normal operation, ANS and ADP methods are carried as AITP
      segments (Protocol = 1, AITP).  Protocol = 2 (ANS) and Protocol =
      3 (ADP) are reserved for future use cases where a lightweight,
      single-datagram exchange bypasses AITP association overhead — for
      example, bootstrap resolution when no AITP association can yet be
      established, or one-shot name announcements in resource-
      constrained environments.  Until such uses are formally specified,
      conforming implementations SHOULD use Protocol = 1 (AITP) for all
      ANS and ADP exchanges, and MUST silently discard messages with
      Protocol values 2 or 3 if they do not implement direct-datagram
      handlers for those protocols.

   TTL (4 bits)  Time to Live.  An upper bound on the number of relay
      hops.  Each relaying node MUST decrement the TTL by 1.  When the
      TTL reaches zero, the message MUST be discarded; if the ERR flag
      is set, an ERROR message with code TTL_EXPIRED SHOULD be returned
      to the source.



Song & Yuan             Expires 26 September 2026              [Page 11]

Internet-Draft                     AIP                        March 2026


      The default TTL is 8.  Valid range is 0-15.  A TTL of 0 means the
      message MUST NOT be relayed; it is delivered only if the
      destination is local.

   Flags (4 bits)  A bitmask of control flags:

       +=======+=======+======+=======================================+
       | Bit   | Value | Name | Description                           |
       +=======+=======+======+=======================================+
       | 3     | 0x8   | SIG  | Message carries an Ed25519 signature  |
       | (MSB) |       |      | (64 octets) appended after the        |
       |       |       |      | payload.                              |
       +-------+-------+------+---------------------------------------+
       | 2     | 0x4   | ERR  | Error report requested.  If delivery  |
       |       |       |      | fails, an ERROR message SHOULD be     |
       |       |       |      | returned to the source.               |
       +-------+-------+------+---------------------------------------+
       | 1     | 0x2   | SEM  | Semantic resolution provenance.  When |
       |       |       |      | clear, AIP performs exact URI         |
       |       |       |      | resolution (the baseline).  When set, |
       |       |       |      | the message was delivered via         |
       |       |       |      | resolver-assisted semantic discovery: |
       |       |       |      | AIP resolved a natural-language query |
       |       |       |      | through DISCOVER before transmission. |
       |       |       |      | The Destination URI field carries the |
       |       |       |      | resolved agent:// URI; the original   |
       |       |       |      | query is recorded in the SemQuery     |
       |       |       |      | option (Type 5, Section 4.3).         |
       |       |       |      | Whether the resolver supports         |
       |       |       |      | semantic resolution is deployment-    |
       |       |       |      | specific (see Section 5.2).           |
       +-------+-------+------+---------------------------------------+
       | 0     | 0x1   | RLY  | Relay permitted.  If set,             |
       | (LSB) |       |      | intermediate nodes MAY forward this   |
       |       |       |      | message toward the destination.       |
       +-------+-------+------+---------------------------------------+

                            Table 3: AIP Flag Bits

   Reserved (8 bits)  Reserved for future use.  Senders MUST set this
      field to zero.  Receivers MUST ignore this field.

   Message ID (32 bits)  A sender-assigned identifier for deduplication
      and request-response correlation.  Implementations MUST ensure
      uniqueness among outstanding messages to the same destination.  A
      monotonically increasing counter is one possible strategy.

   Payload Length (32 bits)  The length in octets of the payload (not



Song & Yuan             Expires 26 September 2026              [Page 12]

Internet-Draft                     AIP                        March 2026


      including the header, address block, or options).  Maximum value
      is 65535; implementations MUST reject messages with Payload Length
      exceeding 65535.

   Src URI Len (8 bits)  The length in octets of the wire-encoded Source
      URI.  A value of 0 is permitted only in ERROR messages (system-
      generated error with no agent source).  Maximum 255.

   Dst URI Len (8 bits)  The length in octets of the wire-encoded
      Destination URI.  MUST NOT be 0.  Maximum 255.

   Options Length (16 bits)  The total length in octets of the TLV
      options region, including any padding.  If no options are present,
      this field is 0.  Maximum 65535.  The options region MUST be
      padded to a 4-octet boundary.

   Source URI (variable, 0-255 octets)  The agent:// URI of the sender
      in wire-encoded form (without the "agent://" prefix).

   Destination URI (variable, 1-255 octets)  The agent:// URI of the
      intended recipient in wire-encoded form (without the "agent://"
      prefix).  This field always contains a valid wire-encoded agent://
      URI, regardless of whether the SEM flag is set.  When the SEM flag
      is set, AIP resolves the query before transmission and places the
      resolved URI here; the original query is carried in the SemQuery
      option (Section 4.3).

   Address Padding (0-3 octets)  Zero-valued padding octets added after
      the Destination URI to bring the combined address block (Src URI +
      Dst URI + padding) to a 4-octet boundary.

4.3.  TLV Options

   The options region carries zero or more Type-Length-Value (TLV)
   encoded options.  Options provide extensibility without modifying the
   fixed header.

   Each option is encoded as:

   +--------+--------+----------------------------+
   |  Type  | Length  |    Data (Length octets)     |
   +--------+--------+----------------------------+
     1 byte   1 byte    variable

   Exception: Type 0 (Pad1) is a single zero octet with no Length or
   Data fields; it is used for single-octet alignment padding.





Song & Yuan             Expires 26 September 2026              [Page 13]

Internet-Draft                     AIP                        March 2026


   +=========+===========+==========+=================================+
   | Type    | Name      | Length   | Description                     |
   +=========+===========+==========+=================================+
   | 0       | Pad1      | 0        | Single-octet padding (no Length |
   |         |           |          | field).                         |
   +---------+-----------+----------+---------------------------------+
   | 1       | PadN      | N        | Multi-octet padding (N zero     |
   |         |           |          | octets).                        |
   +---------+-----------+----------+---------------------------------+
   | 2       | Timestamp | 8        | UTC Unix timestamp in           |
   |         |           |          | microseconds (uint64, big-      |
   |         |           |          | endian).  Used for latency      |
   |         |           |          | measurement and replay          |
   |         |           |          | rejection.                      |
   +---------+-----------+----------+---------------------------------+
   | 3       | Trace     | variable | Opaque trace context blob for   |
   |         |           |          | distributed tracing.            |
   |         |           |          | Implementations MAY use W3C     |
   |         |           |          | Trace Context traceparent       |
   |         |           |          | format or any other tracing     |
   |         |           |          | scheme.                         |
   +---------+-----------+----------+---------------------------------+
   | 4       | Priority  | 1        | Message priority hint (0 =      |
   |         |           |          | lowest, 255 = highest).         |
   |         |           |          | Receivers MAY use this for      |
   |         |           |          | scheduling.                     |
   +---------+-----------+----------+---------------------------------+
   | 5       | SemQuery  | variable | UTF-8 semantic query string.    |
   |         |           |          | MUST be present when the SEM    |
   |         |           |          | flag is set; MUST NOT be        |
   |         |           |          | present when the SEM flag is    |
   |         |           |          | clear.  Records the original    |
   |         |           |          | natural-language query used for |
   |         |           |          | resolver-assisted discovery.    |
   +---------+-----------+----------+---------------------------------+
   | 6-127   |           |          | Available for future assignment |
   |         |           |          | (IANA).                         |
   +---------+-----------+----------+---------------------------------+
   | 128-254 |           |          | Available for experimental /    |
   |         |           |          | private use.                    |
   +---------+-----------+----------+---------------------------------+
   | 255     |           |          | Reserved.                       |
   +---------+-----------+----------+---------------------------------+

                      Table 4: Standard AIP Options






Song & Yuan             Expires 26 September 2026              [Page 14]

Internet-Draft                     AIP                        March 2026


   The entire options region MUST be padded to a 4-octet boundary using
   Pad1 or PadN options.  Implementations MUST ignore unrecognized
   option types (skip by reading Type and Length, then advancing Length
   octets).

4.4.  Message Signature

   When the SIG flag (bit 3) is set, the message carries a 64-octet
   Ed25519 signature appended immediately after the payload.  The
   signature MUST NOT be included in the Payload Length field; receivers
   detect its presence via the SIG flag.

   The signature is computed over:

   sign_input = fixed_header (16 octets, with Reserved set to 0)
              || src_uri_wire
              || dst_uri_wire
              || options_data (without padding)
              || payload

   The signing key is the Ed25519 private key corresponding to the
   source agent's identity.  Verification uses the public key bound to
   the source agent:// URI; the receiver obtains this key from its local
   resolver (see Section 9.2).  The node's link-layer Peer ID is used
   only for message delivery, not for signature verification.

   Implementations SHOULD set the SIG flag on all messages in production
   deployments.  Implementations MUST verify signatures on incoming SIG-
   flagged messages and MUST discard messages with invalid signatures.

5.  Local Resolver

   AIP delegates all name resolution to a local resolver service.  The
   resolver maps agent:// URIs to peer IDs that AIP can use for link-
   layer transmission.

   AIP makes no assumptions about resolver internals.  Any service that
   satisfies the Resolver interface (Section 5.1) is acceptable.  ANS
   [I-D.song-anp-ans] is one companion resolver architecture.

5.1.  Resolver Interface

   The resolver MUST provide:

   RESOLVE(uri) -> (peer_id, ok)  Maps a fully-qualified agent:// URI to
      a peer ID.  Returns ok = false if the URI cannot be resolved.

   IS_LOCAL(uri) -> bool  Returns true if the URI is registered by an



Song & Yuan             Expires 26 September 2026              [Page 15]

Internet-Draft                     AIP                        March 2026


      agent on the local node.

   The resolver MAY use any local data structure (cache, table, or
   database) to satisfy these operations.  AIP does not constrain
   resolver internals, storage model, propagation mechanism, or ranking
   method.  Additional resolver operations such as registration and
   unregistration are outside AIP's scope and are defined by the
   resolver specification.

5.2.  Optional Semantic Resolver Extension

   A resolver MAY additionally support the following operation for use
   with the SEM flag (Section 6.2):

   DISCOVER(query, tags, namespace, limit) -> list of (uri, peer_id,
   score)  Maps a natural-language query to a ranked list of matching
      agents.  A resolver that does not support semantic resolution MUST
      return an empty list.

   Implementations that do not support semantic resolution are fully
   conformant with this specification.

5.3.  Requirements on Implementations

   Every AIP module MUST be initialized with a resolver.  If no full
   resolver is available, a minimal implementation that only supports
   exact lookup of locally registered URIs is sufficient.

   The resolver SHOULD cache results to avoid repeated lookups for the
   same URI.  Cache entries SHOULD expire based on a TTL provided by the
   resolver.  Implementations MUST enforce a maximum cache size to
   prevent unbounded memory growth; deployment-specific defaults are
   expected.

6.  Name Resolution

   AIP resolves destination URIs by calling the local resolver
   (Section 5.1).  Baseline AIP operation uses exact destination tokens;
   resolver-assisted semantic discovery is an optional extension that
   occurs before forwarding.  Once a destination URI has been selected,
   AIP forwarding proceeds identically in both cases.

   The resolution strategy depends on the SEM flag:








Song & Yuan             Expires 26 September 2026              [Page 16]

Internet-Draft                     AIP                        March 2026


6.1.  Exact Resolution (SEM flag clear)

   When the SEM flag is clear, the Destination URI is a fully- qualified
   agent:// URI.  AIP calls RESOLVE(uri) on the local resolver.  If the
   resolver returns ok = true, AIP uses the returned peer ID for
   transmission.  If ok = false, AIP returns NAME_NOT_FOUND to the upper
   layer.

   The resolver MAY use local or distributed mechanisms to satisfy the
   lookup; these mechanisms are outside AIP's scope.

6.2.  Semantic Resolution (SEM flag set) -- Optional Extension

   Semantic resolution is an *optional extension*.  AIP implementations
   are fully conformant without it.  A resolver that does not support
   semantic resolution MUST return an empty list from DISCOVER, causing
   AIP to return NAME_NOT_FOUND.

   When the SEM flag is set and the resolver supports semantic
   resolution, AIP calls DISCOVER(query, ...) on the local resolver and
   uses the highest-scoring result.  AIP places the resolved agent://
   URI in the Destination URI field and records the original query
   string in the SemQuery option (Type 5).  If the resolver returns an
   empty list, AIP returns NAME_NOT_FOUND to the upper layer.

   AIP does not specify any particular scoring algorithm.  The scoring
   strategy -- including text similarity, tag matching, freshness, and
   trust signals -- is defined by the resolver implementation.
   Appendix A provides an informative example using one possible scoring
   formula.

   A failed semantic query (empty result list) causes AIP to return
   NAME_NOT_FOUND.  AIP does not perform query rewriting, fallback
   searches, or multi-step retrieval; such behavior, if desired, is the
   responsibility of the resolver or the application.

   After resolution, AIP performs ordinary exact-URI delivery; semantic
   interpretation is confined to resolver selection and is not part of
   the forwarding semantics.  The SEM flag does not alter forwarding
   behavior; it records resolver-assisted destination selection
   provenance for policy, debugging, and audit purposes.










Song & Yuan             Expires 26 September 2026              [Page 17]

Internet-Draft                     AIP                        March 2026


7.  Message Processing

   This section defines AIP's complete processing model.  The send and
   receive paths described below are self-contained: they depend only on
   the local resolver interface (Section 5.1) and the link-layer
   TRANSMIT/DELIVER primitives (Section 8.2).  No knowledge of companion
   protocols is required to implement these paths.

7.1.  Sending

   When the upper layer calls SEND:

   1.  *Validate the source URI.*

       The source URI MUST be locally registered (IS_LOCAL returns
       true).  If not, the send operation MUST fail.

   2.  *Resolve the destination.*

       If the SEM flag is clear, call RESOLVE(destination) on the local
       resolver.  If the SEM flag is set, call DISCOVER(destination,
       ...) and use the highest-scoring result; place the resolved
       agent:// URI in the Destination URI field and record the original
       query in a SemQuery option (Type 5).  If resolution fails, return
       NAME_NOT_FOUND to the upper layer.

   3.  *Construct the message.*

       Build the 16-octet fixed header with Version = 1, Type, Protocol,
       TTL (default 8), Flags, Reserved = 0, auto- generated Message ID,
       Payload Length.  Wire-encode source and destination URIs.  Encode
       any options (including the SemQuery option if SEM flag is set).

   4.  *Sign (if SIG flag set).*

       Compute the Ed25519 signature per Section 4.4 and append it after
       the payload.

   5.  *Transmit.*

       Serialize and call the link layer's TRANSMIT with the resolved
       peer ID and the serialized bytes.

7.2.  Receiving

   When the link layer delivers bytes:

   1.  *Parse and validate.*



Song & Yuan             Expires 26 September 2026              [Page 18]

Internet-Draft                     AIP                        March 2026


       Decode fixed header.  If Version is unrecognized, discard.  If
       Type is unrecognized, discard.  If the total data is shorter than
       the computed message size, discard.

   2.  *Verify signature (if SIG flag set).*

       Extract the 64-byte signature.  Verify against the public key
       bound to the source agent:// URI, as obtained from the local
       resolver (see Section 9.2).  If verification fails, discard.  If
       ERR flag is set, SHOULD send INVALID_SIGNATURE error.

   3.  *Deduplicate.*

       Check (Source URI, Message ID) against a bounded deduplication
       cache.  If a match exists, discard.  Otherwise, add to cache.

   4.  *Check TTL.*

       If TTL is 0 and destination is not local, discard.  If ERR flag
       is set, send TTL_EXPIRED error.

   5.  *Deliver or relay.*

       If IS_LOCAL(destination) returns true, decrement TTL and dispatch
       to the upper-layer handler identified by the Protocol field.  If
       not local and RLY flag is set and TTL > 0, decrement TTL, call
       RESOLVE(destination) to obtain the next-hop peer, and re-
       transmit.  If not local and RLY is not set, discard.

7.3.  Error Handling

   When an error occurs and the ERR flag is set, the AIP module SHOULD
   generate an ERROR message (Type = 1) to the original source.  ERROR
   generation is best-effort; it is not guaranteed and MAY itself be
   suppressed under overload or resource constraints.  ERROR messages
   MUST NOT be generated in response to other ERROR messages (preventing
   loops).

   The error payload is encoded as:

   +--------+--------+--------+--------+--------+---...---+
   |  Code  | Reservd|     Original Message ID   | Detail  |
   +--------+--------+--------+--------+--------+---...---+
     1 byte   1 byte        4 bytes              variable







Song & Yuan             Expires 26 September 2026              [Page 19]

Internet-Draft                     AIP                        March 2026


       +=======+===================+==============================+
       | Code  | Name              | Description                  |
       +=======+===================+==============================+
       | 0     |                   | Reserved (MUST NOT be used). |
       +-------+-------------------+------------------------------+
       | 1     | NAME_NOT_FOUND    | Destination URI could not be |
       |       |                   | resolved.                    |
       +-------+-------------------+------------------------------+
       | 2     | TTL_EXPIRED       | Message TTL reached zero     |
       |       |                   | before delivery.             |
       +-------+-------------------+------------------------------+
       | 3     | MSG_TOO_LARGE     | Message exceeds maximum size |
       |       |                   | (65535 octets payload).      |
       +-------+-------------------+------------------------------+
       | 4     | INVALID_SIGNATURE | Ed25519 signature            |
       |       |                   | verification failed.         |
       +-------+-------------------+------------------------------+
       | 5     | RATE_LIMITED      | Sender exceeded rate limit.  |
       +-------+-------------------+------------------------------+
       | 6     | PROTOCOL_ERROR    | Malformed message or         |
       |       |                   | protocol violation.          |
       +-------+-------------------+------------------------------+
       | 7     | SHUTTING_DOWN     | Receiving node is shutting   |
       |       |                   | down gracefully.             |
       +-------+-------------------+------------------------------+
       | 8     | INTERNAL_ERROR    | Unspecified internal         |
       |       |                   | processing error.            |
       +-------+-------------------+------------------------------+
       | 9-255 |                   | Available for future         |
       |       |                   | assignment (IANA).           |
       +-------+-------------------+------------------------------+

                         Table 5: AIP Error Codes

   The Original Message ID field MUST carry the full 32-bit Message ID
   of the message that triggered the error, enabling precise
   correlation.  The Detail field is a UTF-8 string providing additional
   context; it MAY be empty.

7.4.  Deduplication

   In a GossipSub topology, messages may arrive via multiple paths.
   Implementations MUST maintain a deduplication cache keyed by (Source
   URI, Message ID).  Messages matching a cache entry MUST be silently
   discarded.  Implementations MUST bound the cache size and entry
   lifetime to prevent unbounded resource consumption; deployment-
   specific defaults are expected.




Song & Yuan             Expires 26 September 2026              [Page 20]

Internet-Draft                     AIP                        March 2026


7.5.  Rate Limiting

   Implementations MUST enforce per-peer rate limiting to prevent
   denial-of-service.  Specific thresholds are deployment-specific;
   implementations SHOULD document their default values.  Messages
   exceeding the rate limit SHOULD be discarded; if the ERR flag is set,
   a RATE_LIMITED error SHOULD be returned.

8.  Interfaces

8.1.  Upper Layer Interface (AITP and others)

   AIP provides the following service primitives to upper-layer
   protocols:

   SEND(source, destination, protocol, payload, options) ->
   message_id  Sends a datagram.

      *  *source* -- agent:// URI.  MUST be locally registered.

      *  *destination* -- an agent:// URI token for baseline delivery;
         when the SEM flag is requested, the caller MAY provide a
         semantic query string, which the local resolver MUST resolve to
         an agent:// URI before transmission.

      *  *protocol* -- upper-layer protocol number (0-255).

      *  *payload* -- opaque bytes.

      *  *options* -- optional: type, ttl, flags, message_id, TLV
         options list.

      Returns: Message ID, or error.

   RECEIVE callback(source, destination, protocol, payload,
   message_id, options)  Invoked when a message arrives for a locally
      registered agent.  The Protocol field identifies which upper-layer
      handler receives the callback.

   Note: Registration, unregistration, and semantic discovery are
   resolver operations, not AIP primitives.

8.2.  Lower Layer Interface (Link Layer)

   TRANSMIT(peer_id, raw_bytes)  Sends bytes to a peer.  The link layer
      routes them using whatever technology is available (libp2p, TCP,
      QUIC, WS, Bluetooth, etc.).




Song & Yuan             Expires 26 September 2026              [Page 21]

Internet-Draft                     AIP                        March 2026


   DELIVER callback(peer_id, raw_bytes)  Invoked by the link layer for
      each received message.  AIP registers this callback during
      initialization.

   AIP makes no assumptions about the link layer beyond these two
   primitives.

9.  Security Considerations

9.1.  Message Authentication

   When the SIG flag is set, AIP messages carry an Ed25519 signature
   providing origin authentication and integrity protection.
   Implementations SHOULD set the SIG flag on all messages.
   Implementations MUST verify signatures before processing signed
   messages and MUST discard messages with invalid signatures.

   Signature verification is performed against the public key bound to
   the source agent:// URI; node Peer IDs are link- layer artifacts and
   are not used for application-layer signature verification.  The
   receiver obtains the URI-to-key binding from its local resolver (see
   Section 9.2).

9.2.  Identity and Signing Key Relationship

   Each agent possesses its own Ed25519 key pair.  A node's link-layer
   Peer ID is derived from one Ed25519 public key, but multiple agents
   MAY run on a single node, each with a distinct key pair and agent://
   URI.

   When multiple agents share a node, the message signature binds the
   payload to the *agent's* key, not the node's Peer ID.  The receiver
   obtains the agent's public key from the resolver (which maintains the
   URI-to-public-key binding).

   Relay nodes that forward messages on behalf of others need not verify
   the signature; only the final destination endpoint MUST verify.
   Relay nodes MAY verify opportunistically if they have access to the
   signing key.

9.3.  Name Spoofing

   AIP relies on the resolver to verify that agent:// URIs are bound to
   legitimate Ed25519 public keys.  The specifics of name registration
   verification are defined by the resolver specification.






Song & Yuan             Expires 26 September 2026              [Page 22]

Internet-Draft                     AIP                        March 2026


9.4.  Resolution Poisoning

   A malicious resolver could return forged peer IDs, directing messages
   to an attacker.  Mitigations:

   *  Implementations SHOULD use the SIG flag so that receivers can
      verify message authenticity independent of resolution correctness.

   *  Resolver implementations SHOULD require Ed25519 signatures on all
      name entries.

9.5.  Replay Attacks

   Mitigated by:

   *  Deduplication cache: (Source URI, Message ID) pairs.

   *  TTL: bounded hop count limits propagation.

   *  Timestamp option: implementations SHOULD include the Timestamp
      option and reject messages outside a deployment-specific freshness
      window.

9.6.  Resource Exhaustion

   Per-peer rate limiting (Section 7.5), maximum message size (65535
   octets), and resolver cache capacity limits prevent resource
   exhaustion.

9.7.  Semantic Resolution Gaming

   When the SEM flag is used, the quality of results depends on the
   resolver's scoring algorithm.  Resolver implementations SHOULD
   incorporate anti-gaming measures such as trust signals and keyword-
   repetition dampening.  These defenses are outside AIP's scope and are
   defined by the resolver specification.

   If the SEM flag is set but the SemQuery option is absent or
   malformed, implementations MUST treat the message as a protocol error
   and discard it.  When the SIG flag is also set, the SemQuery option
   is covered by the signed message envelope, protecting provenance
   integrity.









Song & Yuan             Expires 26 September 2026              [Page 23]

Internet-Draft                     AIP                        March 2026


9.8.  Privacy

   Agent:// URIs, resolver metadata, and message headers are visible to
   network participants.  AIP does not provide payload confidentiality
   (AITP's responsibility) or metadata privacy.  Applications requiring
   metadata privacy SHOULD use privacy-preserving lower-layer routing
   mechanisms.

10.  IANA Considerations

   This document requests the creation of four new IANA registries and
   the registration of a URI scheme.

10.1.  URI Scheme Registration: agent

   Per [RFC7595], the "agent" URI scheme is registered as follows:

   Scheme name  agent

   Status  Provisional

   Applications/protocols that use this scheme  Agent Internet Protocol
      (AIP), Agent Invocation Transport Protocol (AITP), Agent Name
      System (ANS).

   Contact  Jinke Song <ink@chatchat.space>

   Change controller  Jinke Song <ink@chatchat.space>

   Reference  [this document], Section 3

10.2.  AIP Message Type Registry

   Registry with 4-bit values (0-15).  Registration policy:
   Specification Required.  Initial values in Table 1.

10.3.  AIP Protocol Number Registry

   Registry with 8-bit values (0-255).  Registration policy:
   Specification Required for 4-127, First Come First Served for
   128-254.  Value 255 is reserved for experimental use.  Initial values
   in Table 2.

10.4.  AIP Error Code Registry

   Registry with 8-bit values (0-255).  Value 0 reserved (MUST NOT use).
   Registration policy: Specification Required.  Initial values in
   Table 5.



Song & Yuan             Expires 26 September 2026              [Page 24]

Internet-Draft                     AIP                        March 2026


10.5.  AIP Flag Bits Registry

   Registry with 4 bit positions (0-3).  Registration policy:
   Specification Required.  Initial values in Table 3.

10.6.  AIP Option Type Registry

   Registry with 8-bit values (0-255).  Registration policy:
   Specification Required for 0-127, First Come First Served for
   128-254, value 255 reserved.  Initial values in Table 4.

11.  Implementation Status

   Per [RFC7942], this section records known implementations.

11.1.  ClawNet

   Organization  ChatChatTech

   URL  https://github.com/ChatChatTech/ClawNet

   Description  Go implementation of the full ANP suite.  The AIP module
      (aip/ directory) implements the 16-octet fixed header, Protocol
      field demux, TLV options, local resolver interface, Ed25519
      signature support, and deduplication cache.  The reference
      implementation is being completed as part of the full ClawNet
      stack conforming to AIP, ANS, AITP, and ADP; protocol boundaries
      are exercised in integration tests across the stack.

   Maturity  Alpha

   Coverage  Implemented in current prototype:

      *  16-octet header, Protocol demux, TLV option codec

      *  Local resolver interface, SEM flag delegation

      *  Deduplication cache, source URI validation, relay counting

      *  Message signature support (SIG flag codec)

      *  Max payload validation (65535)

      Under integration; expected complete before final publication
      candidate:

      *  Ed25519 signature verification on receive




Song & Yuan             Expires 26 September 2026              [Page 25]

Internet-Draft                     AIP                        March 2026


      *  Per-peer rate limiting

      *  Timestamp replay rejection

      The items above affect robustness and enforcement behavior; they
      do not alter the wire format, message semantics, or protocol
      boundaries defined in this document.

   Language  Go

   License  Open source

   Contact  ink@chatchat.space

12.  References

12.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC7595]  Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
              and Registration Procedures for URI Schemes", BCP 35,
              RFC 7595, DOI 10.17487/RFC7595, June 2015,
              <https://www.rfc-editor.org/info/rfc7595>.

12.2.  Informative References

   [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791,
              DOI 10.17487/RFC0791, September 1981,
              <https://www.rfc-editor.org/info/rfc791>.




Song & Yuan             Expires 26 September 2026              [Page 26]

Internet-Draft                     AIP                        March 2026


   [RFC1035]  Mockapetris, P., "Domain Names - Implementation and
              Specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
              November 1987, <https://www.rfc-editor.org/info/rfc1035>.

   [RFC7942]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", BCP 205,
              RFC 7942, DOI 10.17487/RFC7942, July 2016,
              <https://www.rfc-editor.org/info/rfc7942>.

   [I-D.song-anp-aitp]
              Song, J., "Agent Invocation Transport Protocol (AITP)",
              Work in Progress, Internet-Draft, draft-song-anp-aitp-00,
              March 2026, <https://datatracker.ietf.org/doc/html/draft-
              song-anp-aitp-00>.

   [I-D.song-anp-ans]
              Song, J., "Agent Name System (ANS)", Work in Progress,
              Internet-Draft, draft-song-anp-ans-00, March 2026,
              <https://datatracker.ietf.org/doc/html/draft-song-anp-ans-
              00>.

   [I-D.song-anp-adp]
              Song, J., "Agent Description Protocol (ADP)", Work in
              Progress, Internet-Draft, draft-song-anp-adp-00, March
              2026, <https://datatracker.ietf.org/doc/html/draft-song-
              anp-adp-00>.

Appendix A.  Example Resolver Scoring (Informative)

   This appendix is entirely informative.  It does not define any
   normative behavior and does not constrain AIP interoperability.
   Implementations are free to use any scoring strategy or none at all.

   This appendix illustrates one possible scoring strategy that a
   semantic resolver could use.  AIP does not mandate any particular
   scoring algorithm; this example is provided for implementers'
   reference.

   The composite score for each candidate is computed as a weighted sum
   of five components:

   score = w_text  * S_text      (BM25 text similarity, k1=1.2, b=0.75)
         + w_tag   * S_tag       (Jaccard tag overlap)
         + w_ns    * S_ns        (namespace match)
         + w_fresh * S_fresh     (1 / (1 + age_hours))
         + w_trust * S_trust     (trust score / max_trust)

   Example weights: 0.4, 0.3, 0.05, 0.05, 0.2 (sum = 1.0).



Song & Yuan             Expires 26 September 2026              [Page 27]

Internet-Draft                     AIP                        March 2026


   Worked example with three resolver entries:

   +=+===================+==============+==============+======+=======+
   |#| URI               | Description  | Skills       | Age  | Trust |
   +=+===================+==============+==============+======+=======+
   |1| agent://acme/fr-  | French to    | translation, | 2h   | 0.85  |
   | | translator        | English      | french,      |      |       |
   | |                   | translation  | english      |      |       |
   | |                   | service      |              |      |       |
   +-+-------------------+--------------+--------------+------+-------+
   |2| agent://babel/    | Universal    | translation, | 0.5h | 0.92  |
   | | universal         | text         | multilingual |      |       |
   | |                   | translator,  |              |      |       |
   | |                   | 50 languages |              |      |       |
   +-+-------------------+--------------+--------------+------+-------+
   |3| agent://research/ | Academic     | research,    | 1h   | 0.70  |
   | | paper-search      | paper search | search       |      |       |
   | |                   | and          |              |      |       |
   | |                   | retrieval    |              |      |       |
   +-+-------------------+--------------+--------------+------+-------+

                    Table 6: Example Resolver Entries

   Query: "translate French text", tags: ["translation", "french"],
   max_poi = 0.92.

Component scores:

          S_text  S_tag   S_ns  S_fresh          S_trust
Entry 1:  1.000   0.667   0     1/(1+2.0)=0.333  0.85/0.92=0.924
Entry 2:  0.664   0.333   0     1/(1+0.5)=0.667  0.92/0.92=1.000
Entry 3:  0.096   0.000   0     1/(1+1.0)=0.500  0.70/0.92=0.761

Composite (w_text=0.4, w_tag=0.3, w_ns=0.05, w_fresh=0.05, w_trust=0.2):

Entry 1: 0.4*1.000 + 0.3*0.667 + 0.05*0 + 0.05*0.333 + 0.2*0.924
       = 0.400 + 0.200 + 0.000 + 0.017 + 0.185 = 0.802

Entry 2: 0.4*0.664 + 0.3*0.333 + 0.05*0 + 0.05*0.667 + 0.2*1.000
       = 0.266 + 0.100 + 0.000 + 0.033 + 0.200 = 0.599

Entry 3: 0.4*0.096 + 0.3*0.000 + 0.05*0 + 0.05*0.500 + 0.2*0.761
       = 0.038 + 0.000 + 0.000 + 0.025 + 0.152 = 0.215

   Result: Entry 1 (0.802) > Entry 2 (0.599) > Entry 3 (0.215).  All
   above threshold (0.1).





Song & Yuan             Expires 26 September 2026              [Page 28]

Internet-Draft                     AIP                        March 2026


Appendix B.  Network Bootstrap (Informative)

   This appendix is entirely informative.  It describes a recommended
   bootstrap sequence for a new agent joining an ANP network for the
   first time.  The steps below depend on companion protocols (AITP,
   ANS, ADP) and link-layer infrastructure; they do not alter AIP's wire
   format or processing rules.

B.1.  Bootstrap Sequence

   1.  *Key Generation.*

       The agent generates an Ed25519 key pair.  The public key derives
       the node's link-layer Peer ID.  This step is entirely local and
       requires no network interaction.

   2.  *Seed Peer Discovery.*

       The agent obtains the Peer IDs and network addresses of one or
       more seed peers (also called bootstrap nodes).  Seed information
       may come from a compiled-in bootstrap list, a DNS SRV record (see
       ANS [I-D.song-anp-ans], Appendix A), a well-known URI, an out-of-
       band configuration file, or manual input.  At least one seed peer
       must be reachable for the remaining steps.

   3.  *Link-Layer Connection.*

       The agent's link-layer module (e.g., libp2p) establishes a
       transport connection to a seed peer using the seed's Peer ID and
       address.  Upon connection, mutual peer authentication occurs at
       the link layer (e.g., Noise handshake in libp2p).

   4.  *DHT Join.*

       The agent joins the Kademlia DHT through the seed peer,
       populating its routing table.  After this step, the agent can
       perform DHT get/put operations.

   5.  *Name Registration.*

       The agent constructs an ANS Name Record binding its chosen
       agent:// URI to its Peer ID, signs it, and submits it via
       ans.register (carried over AITP with Protocol = 1).  The
       receiving peer validates the signature and stores the record.
       The agent also publishes the record to the DHT and announces it
       via GossipSub.

   6.  *Agent Card Publication.*



Song & Yuan             Expires 26 September 2026              [Page 29]

Internet-Draft                     AIP                        March 2026


       The agent constructs an ADP Agent Card describing its
       capabilities and publishes it via adp.advertise (carried over
       AITP, Protocol = 1).  The Agent Card is also stored in the DHT
       under the /clawnet-profile/ namespace.

   7.  *Normal Operation.*

       The agent's local resolver is now populated with at least one
       cached peer (the seed).  AIP can send and receive datagrams.
       AITP associations can be established with any resolved peer.  The
       agent is fully operational.

B.2.  Minimal Bootstrap

   Steps 5 and 6 are not required for baseline AIP operation.  An agent
   that only needs to reach peers by known agent:// URIs can skip name
   registration and Agent Card publication and rely on DHT resolution of
   other agents' names.

   Conversely, an agent that cannot reach any seed peer cannot join the
   network.  AIP itself does not solve seed discovery; implementations
   MUST provide at least one bootstrap mechanism (compiled-in list, DNS,
   manual configuration) as part of their deployment profile.

Appendix C.  Implementation Alignment Notes

   This appendix documents the relationship between this specification
   and the reference implementation in the ClawNet aip/ directory.

   +============+=============================+========================+
   | Spec       | Go Symbol                   | Notes                  |
   | Concept    |                             |                        |
   +============+=============================+========================+
   | Message    | aip.MessageType             | TypeData(0),           |
   | Type       |                             | TypeError(1),          |
   |            |                             | TypePing(2),           |
   |            |                             | TypePong(3).           |
   +------------+-----------------------------+------------------------+
   | Protocol   | aip.Protocol                | ProtoNone(0),          |
   | Number     |                             | ProtoAITP(1),          |
   |            |                             | ProtoANS(2),           |
   |            |                             | ProtoADP(3),           |
   |            |                             | ProtoExpt(255).        |
   |            |                             | (Go source still       |
   |            |                             | uses ProtoATP as a     |
   |            |                             | legacy alias.)         |
   +------------+-----------------------------+------------------------+
   | Flags      | aip.Flags                   | FlagRly(0x1),          |



Song & Yuan             Expires 26 September 2026              [Page 30]

Internet-Draft                     AIP                        March 2026


   |            |                             | FlagSem(0x2),          |
   |            |                             | FlagErr(0x4),          |
   |            |                             | FlagSig(0x8).          |
   +------------+-----------------------------+------------------------+
   | Error Code | aip.ErrorCode               | Full 9-code set.       |
   +------------+-----------------------------+------------------------+
   | Fixed      | fixedHeaderSize = 16        | Byte layout per        |
   | Header     |                             | Figure 1.              |
   +------------+-----------------------------+------------------------+
   | Options    | aip.Option,                 | TLV encoding with      |
   |            | OptPad1..OptPriority        | 4-byte alignment.      |
   +------------+-----------------------------+------------------------+
   | Max        | aip.MaxPayloadSize = 65535  | Enforced in            |
   | payload    |                             | Marshal() and          |
   |            |                             | Unmarshal().           |
   +------------+-----------------------------+------------------------+
   | Local      | aip.LocalResolver           | Implements the         |
   | resolver   | (internal)                  | Resolver interface.    |
   |            |                             | BM25 scoring, LRU      |
   |            |                             | eviction.  The Go      |
   |            |                             | type name is an        |
   |            |                             | implementation         |
   |            |                             | detail; AIP does       |
   |            |                             | not prescribe          |
   |            |                             | resolver internals.    |
   +------------+-----------------------------+------------------------+
   | SEM flag   | Module.Send()               | Delegates to           |
   | resolution |                             | resolver's             |
   |            |                             | Discover() when        |
   |            |                             | FlagSem is set.        |
   +------------+-----------------------------+------------------------+
   | URI        | aip.ParseURI("agent://...") | Validates agent://     |
   | parsing    |                             | prefix, ident          |
   |            |                             | regex.                 |
   +------------+-----------------------------+------------------------+

                    Table 7: Spec-Implementation Mapping

Appendix D.  AIP in Isolation (Informative)

   This appendix is entirely informative.  It illustrates a minimal end-
   to-end message exchange using only AIP primitives, without expanding
   the internals of any companion protocol.

   *Scenario:* Agent A wants to send an AITP payload to
   agent://translation/fr-ja.  The local resolver already has a cached
   mapping for that URI.




Song & Yuan             Expires 26 September 2026              [Page 31]

Internet-Draft                     AIP                        March 2026


   1.  Agent A calls SEND(source="agent://acme/requester",
       destination="agent://translation/fr-ja", protocol=1, payload=...,
       flags={SIG, RLY, ERR}).

   2.  AIP calls IS_LOCAL("agent://acme/requester") -> true.  Source
       validation passes.

   3.  AIP calls RESOLVE("agent://translation/fr-ja") on the local
       resolver.  The resolver returns (peer_id=0xABCD..., ok=true) from
       its cache.  No distributed lookup is needed.

   4.  AIP constructs a DATA message: Version=1, Type=DATA,
       Protocol=AITP(1), TTL=8, Flags=0xD (SIG|ERR|RLY), Message ID=42,
       Payload Length=N.  Source and destination URIs are wire-encoded
       (prefix stripped).

   5.  AIP computes the Ed25519 signature over the header, URIs,
       options, and payload; appends the 64-byte signature.

   6.  AIP calls TRANSMIT(peer_id=0xABCD..., serialized_bytes) on the
       link layer.

   7.  At the receiving node, the link layer calls DELIVER.  AIP parses
       the header, verifies the signature against the public key bound
       to agent://acme/requester, checks deduplication, confirms
       IS_LOCAL("agent://translation/fr-ja") = true, and dispatches the
       payload to the Protocol=1 (AITP) handler.

   At no point does AIP need to know how the resolver obtained its
   mapping, how AITP will process the payload, or what scoring strategy
   (if any) the resolver uses.  AIP's responsibilities are: validate,
   resolve, construct, sign, transmit, and on the receive side: parse,
   verify, dedup, check TTL, deliver or relay.

Authors' Addresses

   Jinke Song
   Dept. of CSE, Hong Kong University of Science and Technology
   Email: ink@chatchat.space


   Mu Yuan
   Dept. of IE, The Chinese University of Hong Kong
   Email: muyuan@cuhk.edu.hk







Song & Yuan             Expires 26 September 2026              [Page 32]
