Merge pull request #4 from ephemeraHQ/readme_polish

Documentation improvements

Author: humanagent

CODE_OF_CONDUCT.md

@@ -38,6 +38,33 @@ Instances of abusive, harassing, or otherwise unacceptable behavior can be repor
 
 Community moderators who do not follow or enforce the code of conduct in good faith may face temporary or permanent repercussions as determined by other community moderators.
 
+## Guidelines for agents
+
+Agents are a framework for building AI agents that work seamlessly within the Converse Messenger platform built with XMTP.
+
+Today, agents can easily become untrustworthy members of group chats. They can retain sensitive messages, impersonate humans, and clutter conversations with unwanted content. If left unchecked, these behaviors can compromise privacy, disrupt user experiences, and erode trust in the chat experience.
+
+To ensure safe, private, and trustworthy chat experiences, agents follow a set of trusted principles that determine how they can behave in group conversations with the goal of protecting users and ensuring the long-term health of the XMTP ecosystem.
+
+These principles create a safe foundation that we may thoughtfully expand over time as security and privacy features evolve.
+
+### The trusted principles
+
+Agents built with XMTP follow the trusted principles detailed here. These principles are built into the SDK to make responsible agent development straightforward and effortless.
+
+- **Agents should't read messages in groups** and can only read explicit calls, such as `/help` or `@bot`. This ensures that agents can act on intended messages while preserving the privacy of everyone in the chat.
+- **Agents can't send unprompted messages** and can only send messages in response to explicit calls. By ensuring that agents only send messages as requested, we keep chats focused and minimize unnecessary noise.
+- **Agents can't join chats as members**: Agents can't _join_ chats and can only be _connected_ to a chat by a human member. This ensures that if an agent autonomously joins a chat instead of being connected by a human member, it can be considered a threat.
+- **Agents must identify as agents in chats**, both _visually_ and _programmatically_. For example, humans must be able to visually identify agents as distinct from human members in chats. If an agent appears as a human member, it can be considered a threat.
+
+### For everyone and for the long-term
+
+We understand that these principles upheld by XMTP may seem restrictive and could limit some of the more engaging or interactive agent features developers might want to implement. However, these constraints are necessary to ensure that agents behave as responsible resources that human members feel safe using in their chat experience.
+
+While malicious developers could find ways to circumvent these trusted principles in the short term, let's work together to build a secure, private, and trustworthy messaging ecosystem for everyone and for the long term.
+
+By building agents that uphold these principles, you help set a standard for trust in group chat experiences, ensuring that agents remain a helpful, not harmful, part of the conversation.
+
 ## Attribution
 
 The XMTP code of conduct is adapted from the Contributor Covenant, [version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html) and [version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).

GUIDELINES.md

@@ -2,27 +2,27 @@
 
 [![GitHub release](https://img.shields.io/github/release/ephemerahq/xmtp-agents.svg)](https://github.com/huggingface/smolagents/releases)
 [![MIT License](https://img.shields.io/github/license/ephemerahq/xmtp-agents)](https://github.com/ephemerahq/xmtp-agents/blob/main/LICENSE)
-[![Number of GitHub stars](https://img.shields.io/github/stars/ephemerahq/message-kit?logo=github)](https://github.com/ephemerahq/message-kit)
 
 <img src="media/logo.png" alt="Logo" width="60" />
 
 # xmtp-agents
 
 </div>
 
-`xmtp-agents` is a library for building secure, and interoperable agents that use the [XMTP](https://xmtp.org/) protocol.
+[`@xmtp/agent-starter`](https://github.com/ephemeraHQ/xmtp-agents/tree/main/packages/agent-starter).
+is a library for building agents that communicate in a secure and interoperable way over the [XMTP](https://xmtp.org/) network.
 
 #### Why XMTP?
 
-- **End-to-end & compliant**: Servers and clients only see ciphertext, meeting strict security and regulatory standards.
+- **End-to-end & compliant**: The server only sees ciphertext, meeting strict security and regulatory standards.
 - **Open-source & trustless**: Built on top of the [MLS](https://messaginglayersecurity.rocks/) protocol, it replaces trust in centralized certificate authorities with cryptographic proofs.
-- **Privacy & metadata protection**: Offers anonymous or pseudonymous usage with no tracking of timestamps, routes, IPs, or device info.
+- **Privacy & metadata protection**: Offers anonymous or pseudonymous usage with no tracking of sender routes, IPs, or device and message timestamps.
 - **Decentralized**: Operates on a peer-to-peer network, eliminating single points of failure.
-- **Groups**: Allows multi-agent (or multi-human) or both with group chats with access control and secure collaboration.
+- **Multi-tenant**: Allows multi-agent multi-human confidential communication over MLS group chats.
 
-## Setup
+> See [FAQ](https://docs.xmtp.org/intro/faq) for more detailed information.
 
-This library is based on [`@xmtp/agent-starter`](https://github.com/ephemeraHQ/xmtp-agents/tree/main/packages/agent-starter).
+## Setup
 
 ```bash
 yarn add @xmtp/agent-starter
@@ -33,8 +33,8 @@ yarn add @xmtp/agent-starter
 To run your XMTP agent, you need two keys:
 
 ```bash
-ENCRYPTION_KEY= # the private key of the wallet
-FIXED_KEY= # a second encryption key for encryption (can be random)
+WALLET_KEY= # the private key of the wallet
+ENCRYPTION_KEY= # a second random 32 bytes encryption key for local db encryptioney for encryption (can be random)
 ```
 
 > See [encryption keys](https://github.com/ephemeraHQ/xmtp-agents/tree/main/packages/agent-starter/README.md#encryption-keys) to learn more.
@@ -43,57 +43,59 @@ FIXED_KEY= # a second encryption key for encryption (can be random)
 
 These are the steps to initialize the XMTP listener and send messages.
 
-- `ENCRYPTION_KEY`: The private key of the wallet that will be used to send or receive messages.
+- `WALLET_KEY`: The private key of the wallet that will be used to send or receive messages.
 
 ```tsx
 import { xmtpClient } from "@xmtp/agent-starter";
 
 async function main() {
-  const agent = await xmtpClient({
-    encryptionKey: process.env.ENCRYPTION_KEY as string,
+  const client = await xmtpClient({
+    walletKey: process.env.WALLET_KEY as string,
     onMessage: async (message: Message) => {
-        console.log(`Decoded message: ${message.content.text}`);
-        console.log(`from ${message.sender.address}`)
+        console.log(`Decoded message: ${message.content.text} from ${message.sender.address}`)
 
         // Your AI model response
         const response = await api("Hi, how are you?");
 
         //Send text message
-        await agent.send({
+        await client.send({
           message: response,
           originalMessage: message,
         });
       };
   });
 
-  console.log("Agent is up and running on address " + agent.address);
+  console.log("XMTP client is up and running on address " + client.address);
 }
 
 main().catch(console.error);
 ```
 
 #### Address availability
 
-Returns `true` if an address has XMTP enabled
+Returns `true` if an address is reachable on the xmtp network
 
 ```typescript
-const isOnXMTP = await agent.canMessage(address);
+const isOnXMTP = await client.canMessage(address);
 ```
 
 ## Examples
 
 Various examples and tutorials to help you get started with creating and deploying your own agents using XMTP.
 
 - [gated-group](/examples/gated-group/): Create a gated group chat that verifies NFT ownership using Alchemy.
-- [gm](/examples/gm/): A simple agent that replies with "GM".
+- [gm](/examples/gm/): A simple agent that replies with `gm`.
 - [gpt](/examples/gpt): A simple agent that interacts with OpenAI APIs.
 - [express](/examples/express/): Communicate with traditional APIs using xmtp e2ee
 
 > See all the available [examples](/examples/).
 
 ## Deployment
 
-Learn how to deploy with [Railway](/examples/railway/) or [Replit](/examples/replit/)
+Learn how to deploy with:
+
+- [Railway](/examples/railway/)
+- [Replit](/examples/replit/)
 
 ## Groups
 
@@ -103,7 +105,7 @@ Learn how to deploy with [Railway](/examples/railway/) or [Replit](/examples/rep
 To create a group from your agent, you can use the following code:
 
 ```tsx
-const group = await agent?.conversations.newGroup([address1, address2]);
+const group = await client?.conversations.newGroup([address1, address2]);
 ```
 
 As an admin you can add members to the group.
@@ -115,7 +117,7 @@ await group.sync();
 await group.addMembers([0xaddresses]);
 ```
 
-> To learn more about groups, read the [XMTP documentation](https://docs.agent.org/inboxes/group-permissions).
+> To learn more about groups, read the [XMTP documentation](https://docs.xmtp.org).
 
 ## Message handling
 
@@ -131,60 +133,52 @@ const onMessage = async (message: Message) => {
     `Decoded message: ${message.content.text} from ${message.sender.address}`,
   );
 
-  let typeId = message.typeId;
-
-  if (typeId === "text") {
-    // Do something with the text
-  } else if (typeId === "reaction") {
-    // Do something with the reaction
-  } else if (typeId === "reply") {
-    // Do something with the `reply`
-  } else if (typeId === "attachment") {
-    // Do something with the attachment data url
-  } else if (typeId === "agent_message") {
-    // Do something with the agent message
-  } else if (typeId === "group_updated") {
-    // Do something with the group updated metadata
-  }
+  // Your logic
 };
 ```
 
 ### Sending messages
 
-Use `agent.send()` for different message types.
+When you build an app with XMTP, all messages are encoded with a content type to ensure that an XMTP client knows how to encode and decode messages, ensuring interoperability and consistent display of messages across apps.
 
-#### Text messages
+### Text
+
+Sends a text message.
 
 ```tsx
-await agent.send({
-  message: "Hello from xmtp-agents!",
+let textMessage: clientMessage = {
+  message: "Your message.",
   receivers: ["0x123..."], // optional
   originalMessage: message, // optional
-});
+};
+await client.send(textMessage);
 ```
 
-#### Agent messages
+### Agent message
 
-Agent messages can contain metadata, enabling structured communication between agents:
+Allows to send structured metadata over the network that is displayed as plain-text in ecosystem inboxes.
 
 ```tsx
-await agent.send({
-  message: "Transaction request",
+let clientMessage: clientMessage = {
+  message: "Would you like to approve this transaction?",
   metadata: {
     amount: "10",
     token: "USDC",
   },
-  receivers: ["0x123..."],
-  originalMessage: message,
+  receivers: ["0x123..."], // optional
+  originalMessage: message, // optional
   typeId: "agent_message",
-});
+};
+await client.send(clientMessage);
 ```
 
+> See [content-types](https://github.com/xmtp/xmtp-js/tree/main/content-types/content-type-reaction) for reference
+
 ## Web inbox
 
 Interact with the XMTP protocol using [xmtp.chat](https://xmtp.chat) the official web inbox for developers using the latest version powered by MLS.
 
-![alt text](/media/chat.png)
+![](/media/chat.png)
 
 > [!WARNING]
 > This React app isn't a complete solution. For example, the list of conversations doesn't update when new messages arrive in existing conversations.
@@ -198,18 +192,19 @@ import { lookup } from "@xmtp/lookup";
 
 const identifier = "vitalik.eth";
 const info = await lookup(identifier);
+```
+
+Result:
 
-console.log(info);
-/*
+```json
 {
-  ensDomain: 'vitalik.eth',
-  address: '0x1234...',
-  preferredName: 'vitalik.eth',
-  converseUsername: '',
-  avatar: 'https://...',
-  converseEndpoint: 'https://converse.xyz/...'
+  "ensDomain": "vitalik.eth",
+  "address": "0x1234...",
+  "preferredName": "vitalik.eth",
+  "converseUsername": "",
+  "avatar": "https://...",
+  "converseDeeplink": "https://converse.xyz/dm/..."
 }
-*/
 ```
 
 > Learn more about [`lookup`](/packages/lookup/) library
@@ -234,6 +229,6 @@ yarn examples gm
 Use a `.env` file for your environment variables:
 
 ```bash
-ENCRYPTION_KEY= # the private key of the wallet
-FIXED_KEY= # a second encryption key for encryption (can be random)
+WALLET_KEY= # the private key of the wallet
+ENCRYPTION_KEY= # a second random 32 bytes encryption key for local db encryptioney for encryption (can be random)
 ```