Add NIP-AE: Agents

2 files changed, 168 insertions, 0 deletions

diff --git a/AE.md b/AE.md
new file mode 100644
index 0000000..18432b8
--- /dev/null
+++ b/AE.md
@@ -0,0 +1,163 @@
+NIP-AE
+======
+
+Agents
+------
+
+`draft` `optional`
+
+Defines event kinds for agent definitions, lessons, nudges, and attribution.
+
+## Terminology
+
+An **agent definition** is a Nostr event describing an agent's identity, capabilities, and behavior. It is a template.
+
+An **agent** is a runtime instance: a signing keypair executing according to an agent definition.
+
+Multiple agents can instantiate from the same definition.
+
+## Behavior Model
+
+An agent's runtime behavior is composed of:
+
+1. **Agent definition** — The base template (kind 4199)
+2. **Lessons** — Behavioral refinements published by agents of the same definition (kind 4129)
+3. **Lesson comments** — Human or agent corrections/additions to lessons (kind 1111)
+
+Execution platforms determine which lessons and comments to apply based on trust.
+
+---
+
+## Agent Definition (Kind 4199)
+
+```json
+{
+  "kind": 4199,
+  "pubkey": "<publisher-pubkey>",
+  "tags": [
+    ["title", "<agent-name>"],
+    ["role", "<expertise-and-personality>"],
+    ["instructions", "<operational-guidelines>"],
+    ["use-criteria", "<when-to-use-this-agent>"],
+    ["description", "<one-line-description>"],
+    ["tool", "<tool-name>"],
+    ["ver", "<version-number>"],
+    ["image", "<avatar-url>"]
+  ],
+  "content": ""
+}
+```
+
+### Tags
+
+- `title` — Agent name
+- `role` — Expertise, personality, approach
+- `instructions` — Operational guidelines
+- `use-criteria` — When to select this agent
+- `description` — One-line description
+- `tool` — Zero or more tags of tool names the agent expects to have
+- `ver` — Version number, defaults to `1`
+- `image` — Avatar URL
+
+---
+
+## Agent Nudge (Kind 4201)
+
+Nudges modify agent behavior and/or tool availability.
+
+```json
+{
+  "kind": 4201,
+  "pubkey": "<publisher-pubkey>",
+  "tags": [
+    ["title", "<nudge-title>"],
+    ["only-tool", "<tool-name>"],
+    ["allow-tool", "<tool-name>"],
+    ["deny-tool", "<tool-name>"]
+  ],
+  "content": "<behavioral-modifier>"
+}
+```
+
+### Tags
+
+- `title` — Short identifier
+- `only-tool` — Agent gets exactly these tools, overrides defaults
+- `allow-tool` — Add tool to default set (ignored if `only-tool` present)
+- `deny-tool` — Remove tool from default set (ignored if `only-tool` present)
+
+Precedence: `only-tool` > `allow-tool`/`deny-tool`. Multiple tool tags allowed.
+
+---
+
+## Agent Lesson (Kind 4129)
+
+Agents publish lessons learned during operation.
+
+```json
+{
+  "kind": 4129,
+  "pubkey": "<agent-pubkey>",
+  "tags": [
+    ["title", "<lesson-title>"],
+    ["category", "<topic-area>"],
+    ["e", "<agent-definition-id>"]
+  ],
+  "content": "<lesson-content>"
+}
+```
+
+### Tags
+
+- `title` — Short summary
+- `e` — Reference to the agent definition (kind 4199)
+- `category` — Topic classification
+
+Humans or agents can refine lessons using NIP-22 comments.
+
+---
+
+## Agent Attribution
+
+### Agent Profile (Kind 0)
+
+Agents publish kind 0 declaring their nature.
+
+- `bot` — Empty tag indicating automated pubkey
+- `e` — Reference to agent definition (kind 4199)
+- `p` — Claimed owner's pubkey
+
+```json
+{
+  "kind": 0,
+  "pubkey": "<agent-pubkey>",
+  "tags": [
+    ["bot"],
+    ["e", "<agent-definition-id>"],
+    ["p", "<owner-pubkey>"]
+  ],
+  "content": "{\"name\":\"Code Reviewer\"}"
+}
+```
+
+### Owner Claims (Kind 14199)
+
+Replaceable event where owners declare their agents.
+
+```json
+{
+  "kind": 14199,
+  "pubkey": "<owner-pubkey>",
+  "tags": [
+    ["p", "<agent-pubkey-1>"],
+    ["p", "<agent-pubkey-2>"]
+  ],
+  "content": ""
+}
+```
+
+### Bidirectional Verification
+
+Verified owner-agent relationship requires:
+1. Agent's kind 0 includes `["p", "<owner-pubkey>"]`
+2. Owner's kind 14199 includes `["p", "<agent-pubkey>"]`
diff --git a/README.md b/README.md
index 2e11906..9106759 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 - [NIP-99: Classified Listings](99.md)
 - [NIP-A0: Voice Messages](A0.md)
 - [NIP-A4: Public Messages](A4.md)
+- [NIP-AE: Agents](AE.md)
 - [NIP-B0: Web Bookmarks](B0.md)
 - [NIP-B7: Blossom](B7.md)
 - [NIP-BE: Nostr BLE Communications Protocol](BE.md)
@@ -178,6 +179,9 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 | `2003`        | Torrent                         | [35](35.md)                            |
 | `2004`        | Torrent Comment                 | [35](35.md)                            |
 | `2022`        | Coinjoin Pool                   | [joinstr][joinstr]                     |
+| `4129`        | Agent Lesson                    | [AE](AE.md)                            |
+| `4199`        | Agent Definition                | [AE](AE.md)                            |
+| `4201`        | Agent Nudge                     | [AE](AE.md)                            |
 | `4550`        | Community Post Approval         | [72](72.md)                            |
 | `5000`-`5999` | Job Request                     | [90](90.md)                            |
 | `6000`-`6999` | Job Result                      | [90](90.md)                            |
@@ -221,6 +225,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 | `11111`       | Transport Method Announcement   | [Nostr Epoxy][nostr-epoxy]             |
 | `13194`       | Wallet Info                     | [47](47.md)                            |
 | `13534`       | Membership Lists                | [43](43.md)                            |
+| `14199`       | Agent List                      | [AE](AE.md)                            |
 | `14388`       | User Sound Effect Lists         | [Corny Chat][cornychat-usersoundlist]  |
 | `17375`       | Cashu Wallet Event              | [60](60.md)                            |
 | `21000`       | Lightning Pub RPC               | [Lightning.Pub][lnpub]                 |