polished readmes

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
@@ -74,7 +74,7 @@ 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);
@@ -115,7 +115,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
 
@@ -151,35 +151,41 @@ const onMessage = async (message: Message) => {
 
 ### 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: agentMessage = {
+  message: "Your message.",
   receivers: ["0x123..."], // optional
   originalMessage: message, // optional
-});
+};
+await agent.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 agentMessage: agentMessage = {
+  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 agent.send(agentMessage);
 ```
 
+> 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.