From ca89f4e93f051239ec85f9e6781caaa019ea0869 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Jun 2025 13:10:23 +0000
Subject: [PATCH 1/3] Initial plan for issue


From 8a07ae25b8b33084d18e9cd2b4888e3796df6f7d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Jun 2025 13:21:41 +0000
Subject: [PATCH 2/3] Set up test content with markdown linting issues to fix

Co-authored-by: mattheworiordan <43789+mattheworiordan@users.noreply.github.com>
---
 protocol/README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/protocol/README.md b/protocol/README.md
index 0c45a07..ba1d3a6 100644
--- a/protocol/README.md
+++ b/protocol/README.md
@@ -146,3 +146,79 @@ based on the `js-web` entry, and then handled as if it sent that `Ably-Agent` he
 
 It is not expected that any new mappings will be added, since we shouldn't be sending any new types of values using the deprecated
 `X-Ably-Lib` header, any newly released code should be sending the `Ably-Agent` header instead.
+
+## Guidance adding custom agents to SDKs and/or Control API
+
+[  Based on the implementation experience, here are the suggested changes for the
+https://github.com/ably/ably-common/blob/main/protocol/README.md to help other Ably engineers add
+custom agents:
+
+## Adding Custom Agent Headers
+
+When implementing Ably functionality in tools, wrappers, or integrations, it's important to add custom
+agent headers to help track usage and debug issues. Here's how to add agent headers in different contexts:
+
+### 1. Using Ably SDK (JavaScript/TypeScript)
+
+For REST or Realtime clients, use the `agents` property in ClientOptions:
+
+```javascript
+const client = new Ably.Realtime({
+  key: 'your-api-key',
+  agents: {
+    'your-agent-name': 'version'  // e.g., 'ably-cli': '0.7.7'
+  }
+});
+```
+
+Note: The agents property may not be in the TypeScript definitions. Use type assertion if needed:
+```javascript
+const options: any = {
+  key: 'your-api-key',
+  agents: { 'your-agent-name': 'version' }
+};
+const client = new Ably.Realtime(options);
+```
+
+2. Direct HTTP Requests
+
+When making direct HTTP requests to Ably APIs, add the Ably-Agent header:
+
+```javascript
+fetch('https://api.ably.com/endpoint', {
+  headers: {
+    'Authorization': 'Bearer your-token',
+    'Ably-Agent': 'your-agent-name/version'  // e.g., 'ably-cli/0.7.7'
+  }
+});
+```
+
+3. Agent Naming Conventions
+
+- Use lowercase kebab-case for agent names (e.g., ably-cli, my-integration)
+- Include version numbers in semantic versioning format (e.g., 1.2.3)
+- For wrappers/tools, use descriptive names that indicate the tool's purpose
+
+4. Adding to agents.json
+
+To officially register your agent, add it to agents.json:
+
+```json
+{
+  "identifier": "your-agent-name",
+  "versioned": true,
+  "type": "wrapper"  // or "tool", "integration", etc.
+}
+```
+
+5. Testing Agent Headers
+
+- For SDK usage: The agent will be automatically included in all REST and WebSocket requests
+- For HTTP requests: Verify the header is present using network inspection tools
+- Consider adding tests to ensure the agent header is included correctly
+
+6. Version Management
+
+- Consider reading version from your local package
+- For compiled/distributed tools, you may need to hardcode the version
+- Remember to update the version when releasing new versions of your tool

From 12a7a81c9ecc99fe93af568f49a06337f41d4e4a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Jun 2025 13:23:32 +0000
Subject: [PATCH 3/3] Fix markdown linting issues in protocol/README.md

Co-authored-by: mattheworiordan <43789+mattheworiordan@users.noreply.github.com>
---
 protocol/README.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/protocol/README.md b/protocol/README.md
index ba1d3a6..0e0408b 100644
--- a/protocol/README.md
+++ b/protocol/README.md
@@ -172,6 +172,7 @@ const client = new Ably.Realtime({
 ```
 
 Note: The agents property may not be in the TypeScript definitions. Use type assertion if needed:
+
 ```javascript
 const options: any = {
   key: 'your-api-key',
@@ -180,7 +181,7 @@ const options: any = {
 const client = new Ably.Realtime(options);
 ```
 
-2. Direct HTTP Requests
+1. Direct HTTP Requests
 
 When making direct HTTP requests to Ably APIs, add the Ably-Agent header:
 
@@ -193,13 +194,13 @@ fetch('https://api.ably.com/endpoint', {
 });
 ```
 
-3. Agent Naming Conventions
+1. Agent Naming Conventions
 
 - Use lowercase kebab-case for agent names (e.g., ably-cli, my-integration)
 - Include version numbers in semantic versioning format (e.g., 1.2.3)
 - For wrappers/tools, use descriptive names that indicate the tool's purpose
 
-4. Adding to agents.json
+1. Adding to agents.json
 
 To officially register your agent, add it to agents.json:
 
@@ -211,13 +212,13 @@ To officially register your agent, add it to agents.json:
 }
 ```
 
-5. Testing Agent Headers
+1. Testing Agent Headers
 
 - For SDK usage: The agent will be automatically included in all REST and WebSocket requests
 - For HTTP requests: Verify the header is present using network inspection tools
 - Consider adding tests to ensure the agent header is included correctly
 
-6. Version Management
+1. Version Management
 
 - Consider reading version from your local package
 - For compiled/distributed tools, you may need to hardcode the version