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/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 new file mode 100644 index 0000000..80db7e9 --- /dev/null +++ b/web/content/docs/observer.mdx @@ -0,0 +1,102 @@ +--- +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 instead — its page +has not been brought forward past the +[v7.1.1 archive](/docs/7.1.1/relay-dashboard) yet. + +## 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/content/docs/reference-cli.mdx b/web/content/docs/reference-cli.mdx index ad1a1de..576212e 100644 --- a/web/content/docs/reference-cli.mdx +++ b/web/content/docs/reference-cli.mdx @@ -43,6 +43,32 @@ 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`. `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 | Command | Description | 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' }, ], }, {