From be6cd77354aee9e2405d56475a005bfa6d7e22fc Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 14:19:26 +0000 Subject: [PATCH 1/3] docs: add a current Observer page built on scoped observer tokens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Observer had no page in the current docs. The slug exists only in the v7.1.1 archive and the legacy nav, so `/docs/observer` redirects into the archive and the current sidebar never mentions the feature at all. The archived page also documents the only method it knew: https://agentrelay.com/observer?key= A workspace key is an administrative credential — it can send messages, spawn agents, and change workspace settings — and a query string is not a place to put one. Current releases ship `agent-relay observer`, which mints a scoped, expiring, read-only `ot_live_` token and builds the link from that. - Adds `web/content/docs/observer.mdx` covering `agent-relay observer`, the `--channels` / `--include-dms` / `--expires` narrowing, `observer list` / `revoke`, the `get_observer_url` MCP tool, and a capability table contrasting a workspace key with an observer token. - Registers the slug under Interfaces in `docsNav`, so the page is reachable and `/docs/observer` resolves to current docs instead of redirecting to the archive. - Leaves the archived v7.1.1 page in place but adds a note that the pattern is unsafe on a current release, linking to the new page. The link is absolute because `rewriteLegacyDocsLinks` rewrites bare `/docs/` links back into `/docs/7.1.1/`, which would have pointed it at itself. Depends on the `agent-relay observer` command in AgentWorkforce/relay#1422. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- web/content/docs/7.1.1/observer.mdx | 9 +++ web/content/docs/observer.mdx | 101 ++++++++++++++++++++++++++++ web/lib/docs-nav.ts | 1 + 3 files changed, 111 insertions(+) create mode 100644 web/content/docs/observer.mdx diff --git a/web/content/docs/7.1.1/observer.mdx b/web/content/docs/7.1.1/observer.mdx index 6b084aa..477383f 100644 --- a/web/content/docs/7.1.1/observer.mdx +++ b/web/content/docs/7.1.1/observer.mdx @@ -22,6 +22,15 @@ https://agentrelay.com/observer?key= The TypeScript SDK exposes this directly as `relay.observerUrl` once the workspace key is available. + + Do not do this on a current release. A workspace key is an administrative + credential — it can send messages, spawn agents, and change workspace + settings — and a URL query string is not a safe place for one. Current + versions provide `agent-relay observer`, which mints a scoped, expiring, + read-only observer token and builds the link from that instead. See the + current [Observer docs](https://agentrelay.com/docs/observer). + + ## When to use it Use Observer when you want visibility without control. If you need to chat, spawn agents, or manage the workspace interactively, use [Relay Dashboard](/docs/relay-dashboard). diff --git a/web/content/docs/observer.mdx b/web/content/docs/observer.mdx new file mode 100644 index 0000000..ff776a7 --- /dev/null +++ b/web/content/docs/observer.mdx @@ -0,0 +1,101 @@ +--- +title: 'Observer' +metaTitle: 'Observer: Watch Agent Relay Traffic in Real Time' +description: 'Share a read-only, expiring link so a human can follow an Agent Relay workspace live — messages, agent activity, and handoffs — without joining the run or handling a workspace key.' +--- + +Observer is a read-only view of a live workspace. Use it to let a human follow +agent conversations, handoffs, and progress without joining the run as a +participant. + +## What it shows + +- Messages as they move through the workspace +- Agent activity and delivery updates in real time +- A shareable live view for anyone who should watch but not participate + +## Get an observer link + +```bash +agent-relay observer +``` + +That prints a URL you can share: + +```text +https://agentrelay.com/observer?key=ot_live_... +``` + +The command mints a scoped **observer token** (`ot_live_...`) and builds the +link from it. By default the token expires in 24 hours and excludes agent DMs. + +Narrow or widen it as needed: + +```bash +agent-relay observer --channels build,review # only these channels +agent-relay observer --include-dms # include agent DMs +agent-relay observer --expires 7d # longer-lived link +agent-relay observer --json # token metadata + URL as JSON +``` + +Manage tokens you have handed out: + +```bash +agent-relay observer list # id, status, expiry (token material is never shown) +agent-relay observer revoke # cut off a link immediately +``` + +An orchestrating agent can do the same through the Agent Relay MCP server with +the `get_observer_url` tool, so a lead can hand you a link without shelling out. + +## Never share a workspace key + +A workspace key (`rk_live_...`) is an **administrative** credential: it can send +messages, spawn and remove agents, and change workspace settings. Do not put one +in an observer URL, a chat message, or a terminal transcript. Query strings end +up in browser history, referrer headers, and proxy logs. + +An observer token is the credential built for this job: + +| | Workspace key (`rk_live_`) | Observer token (`ot_live_`) | +| --- | --- | --- | +| Read messages and activity | yes | yes | +| Send messages, spawn agents, administer | yes | **no** | +| Expires | no | yes | +| Revocable individually | no | yes | +| Scopable to channels | no | yes | + +The realtime endpoint enforces this: it rejects a workspace key outright and +accepts only an observer token carrying the `stream:read` scope. + +## Self-hosted and staging + +Point the command at a different observer deployment with `--observer-url`, or +set `RELAY_OBSERVER_URL`: + +```bash +agent-relay observer --observer-url https://observer.relaycast.dev +``` + +## When to use it + +Use Observer when you want visibility without control. To chat, spawn agents, or +manage the workspace interactively, use the +[Relay Dashboard](/docs/relay-dashboard) instead. + +## Related docs + + + + The credential types Agent Relay issues and what each one can do. + + + Includes `get_observer_url` for orchestrating agents. + + + Every `agent-relay` command, including `observer`. + + + Start a workspace and get agents talking. + + diff --git a/web/lib/docs-nav.ts b/web/lib/docs-nav.ts index cdeba2b..0fe5d3a 100644 --- a/web/lib/docs-nav.ts +++ b/web/lib/docs-nav.ts @@ -56,6 +56,7 @@ export const docsNav: NavGroup[] = [ items: [ { title: 'TypeScript SDK', slug: 'typescript-sdk' }, { title: 'Agent Relay MCP', slug: 'agent-relay-mcp' }, + { title: 'Observer', slug: 'observer' }, ], }, { From 3770144277db0add3e641b22ed6d449bc4616bff Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 10:49:29 +0000 Subject: [PATCH 2/3] docs: document observer in the CLI and MCP references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found the new Observer page pointing at two reference pages that did not actually cover what it promised, and one link into archived docs. - `reference-cli.mdx` called itself the complete command matrix but had no `observer` entry. Adds an Observer section covering the three commands and every flag. - `agent-relay-mcp.mdx` did not list `get_observer_url`. Adds it to the workspace tool inventory plus a section with its inputs, its return shape, and the workspace-key warning. - The "When to use it" link to `/docs/relay-dashboard` resolved to a legacy-only slug, so it silently redirected into the v7.1.1 archive — the same failure this PR set out to fix for Observer. The link is now explicitly labelled as the archive, since Relay Dashboard has no current page yet. Every internal `/docs/` link on the three touched pages now resolves within the current docs, except the one deliberate archive link. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- web/content/docs/agent-relay-mcp.mdx | 21 ++++++++++++++++++++- web/content/docs/observer.mdx | 5 +++-- web/content/docs/reference-cli.mdx | 23 +++++++++++++++++++++++ 3 files changed, 46 insertions(+), 3 deletions(-) diff --git a/web/content/docs/agent-relay-mcp.mdx b/web/content/docs/agent-relay-mcp.mdx index 7760c16..5e2c0db 100644 --- a/web/content/docs/agent-relay-mcp.mdx +++ b/web/content/docs/agent-relay-mcp.mdx @@ -8,7 +8,7 @@ description: 'Expose Agent Relay messaging and registered actions to any agent a `agent-relay mcp` registers three groups of tools: -- workspace and agent tools (`register_agent`, `list_agents`, `add_agent`, `remove_agent`, `create_workspace`, `set_workspace_key`, `spawn`, `submit_result`, `query_nodes`) +- workspace and agent tools (`register_agent`, `list_agents`, `add_agent`, `remove_agent`, `create_workspace`, `set_workspace_key`, `spawn`, `submit_result`, `query_nodes`, `get_observer_url`) - messaging and inbox tools (the table below) - action tools (`list_actions`, `invoke_action`, plus one generated tool per registered action) @@ -78,6 +78,25 @@ calling `spawn` or before asking an operator to bind an app-server agent to a no routes, not a workspace feature flag: a roster entry can be a direct connection, a broker-controlled WebSocket worker, an HTTP push endpoint, or a polling integration. +## Observer Links + +`get_observer_url` mints a scoped, read-only observer token and returns a URL built from it, so an +orchestrating agent can hand a watching human a follow-along link. Requires a workspace key on the +session. + +| Input | Type | Description | +| --- | --- | --- | +| `channels` | `string[]` | Optional. Restrict the view to these channels. Omit to show every channel. | +| `include_dms` | `boolean` | Optional. Include agent DM traffic. Defaults to `false`. | +| `expires_in_hours` | `integer` | Optional. Token lifetime, 1–2160. Defaults to `24`. | + +Returns `url`, `tokenId`, `expiresAt`, `includesDms`, and `channels` when a channel filter was applied. +Revoke a link early with `agent-relay observer revoke `. + +Never build an observer URL from the workspace key. `rk_live_*` is an administrative credential, and the +realtime endpoint rejects it — only a scoped observer token with `stream:read` is accepted. See +[Observer](/docs/observer). + ## Generated Action Tools Each registered action becomes an explicit MCP tool. diff --git a/web/content/docs/observer.mdx b/web/content/docs/observer.mdx index ff776a7..80db7e9 100644 --- a/web/content/docs/observer.mdx +++ b/web/content/docs/observer.mdx @@ -80,8 +80,9 @@ agent-relay observer --observer-url https://observer.relaycast.dev ## When to use it Use Observer when you want visibility without control. To chat, spawn agents, or -manage the workspace interactively, use the -[Relay Dashboard](/docs/relay-dashboard) instead. +manage the workspace interactively, use the Relay Dashboard instead — its page +has not been brought forward past the +[v7.1.1 archive](/docs/7.1.1/relay-dashboard) yet. ## Related docs diff --git a/web/content/docs/reference-cli.mdx b/web/content/docs/reference-cli.mdx index ad1a1de..3cdef85 100644 --- a/web/content/docs/reference-cli.mdx +++ b/web/content/docs/reference-cli.mdx @@ -43,6 +43,29 @@ The SDK-backed groups are `agent`, `channel`, `message`, `integration`, `capabil | `agent-relay workspace switch ` | Switch the active stored workspace. | | `agent-relay workspace active [--json] [--api-url ] [--refresh-timeout ]` | Show the active canonical cloud workspace. | +## Observer + +Mint a read-only link so a human can follow a workspace live. See +[Observer](/docs/observer) for the credential model. + +| Command | Description | +| --- | --- | +| `agent-relay observer [flags]` | Mint a scoped observer token and print the observer URL built from it. | +| `agent-relay observer list [--json]` | List observer tokens for the workspace. Raw token material is never shown. | +| `agent-relay observer revoke ` | Revoke an observer token immediately. | + +| Flag | Description | +| --- | --- | +| `--channels ` | Restrict the view to a comma-separated list of channels. | +| `--include-dms` | Include agent DM traffic. Excluded by default. | +| `--expires ` | Token lifetime such as `30m`, `24h`, `7d`. Defaults to `24h`, maximum `90d`. | +| `--name ` | Token name. Defaults to a generated unique name. | +| `--observer-url ` | Observer dashboard URL (`RELAY_OBSERVER_URL`). Defaults to `https://agentrelay.com/observer`. | +| `--json` | Print the token metadata and URL as JSON. | + +All three accept `--workspace-key` and `--base-url`. The minted token is +read-only and expiring — never build an observer URL from a workspace key. + ## Agents | Command | Description | From cb975f6b4a4eab55bf08dcb4174cd36b33dbd9f7 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 11:16:00 +0000 Subject: [PATCH 3/3] docs: clarify that observer parses its own connection flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review flagged an internal inconsistency: the Observer section says all three commands accept `--workspace-key` and `--base-url`, but the "Common SDK Options" list of SDK-backed groups does not include `observer`. Adding it to that list would have been wrong. `observer` does not use `addSdkOptions` — it declares those two flags itself and has no `--token` at all, because minting an observer token requires the workspace key and an agent token cannot do it. Listing it as SDK-backed would have implied `--token` works there. Says so explicitly instead. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- web/content/docs/reference-cli.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/web/content/docs/reference-cli.mdx b/web/content/docs/reference-cli.mdx index 3cdef85..576212e 100644 --- a/web/content/docs/reference-cli.mdx +++ b/web/content/docs/reference-cli.mdx @@ -63,8 +63,11 @@ Mint a read-only link so a human can follow a workspace live. See | `--observer-url ` | Observer dashboard URL (`RELAY_OBSERVER_URL`). Defaults to `https://agentrelay.com/observer`. | | `--json` | Print the token metadata and URL as JSON. | -All three accept `--workspace-key` and `--base-url`. The minted token is -read-only and expiring — never build an observer URL from a workspace key. +All three accept `--workspace-key` and `--base-url`. `observer` is not one of +the SDK-backed groups above — it declares those two flags itself and takes no +`--token`, because minting an observer token requires the workspace key; an +agent token cannot do it. The minted token is read-only and expiring — never +build an observer URL from a workspace key. ## Agents