chore: refresh agent-relay skills to current CLI surface#85
chore: refresh agent-relay skills to current CLI surface#85willwashburn wants to merge 1 commit into
Conversation
Update orchestrating-agent-relay and using-agent-relay to declaratively describe Agent Relay as it works today. - Lifecycle under `agent-relay local` (up/down/status/metrics/tail) and `local agent` (spawn/list/attach/release); top-level `status` shows workspace + cloud + broker. - Messaging through the `message`/`channel` groups and the relay MCP (`send_dm`, `post_message`, `check_inbox`, `list_messages`, `get_message_thread`, `mark_message_read`); reading replies is a messaging op, never `local tail` (broker debug events). - Orchestrator coordinates via `agent-relay mcp` (auto-registered as `orchestrator`); spawns on the local broker. - Fleet/node model: node-only delivery, capability-based placement, `fleet serve/nodes/config/...`, `capabilities register/list/delete`. - State dir `.agentworkforce/relay/` (connection.json); host `cast.agentrelay.com`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 50 minutes and 55 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for the orchestrating-agent-relay and using-agent-relay skills to align with the new agent-relay CLI command structure, shifting local broker operations to the local command group and messaging to the MCP server or message command group. The review feedback correctly identifies two minor inconsistencies in the troubleshooting table where references to the old up command and the old ${RELAY_API_KEY} environment variable template were missed.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| | Broker not starting | Try `agent-relay local down` first, then `agent-relay local up --background --verbose` and `agent-relay local status --wait-for 10` | | ||
| | Broker not ready after `local status --wait-for` | The process is alive but the broker API is not ready; inspect logs, retry readiness, or restart with `agent-relay local down --force` if it remains stuck | | ||
| | Broker stops immediately after start | Check `ps aux \| grep agent-relay-broker` and `.agentworkforce/relay/connection.json`; if the process is alive but status is stopped, rerun status from the project root or pass `--state-dir` | | ||
| | Half-started broker: process alive but `local status` says stopped and `Failed to read broker connection metadata` | `local up` spawned a broker that never finished writing connection metadata (readiness timed out) and was not cleaned up. Do NOT just retry `up` — it won't reap the orphan. `pkill -f agent-relay-broker` (or `agent-relay local down --force`), delete `.agentworkforce/relay/`, then `agent-relay local up` clean and `agent-relay local status --wait-for 30` | |
There was a problem hiding this comment.
In the updated troubleshooting table, the command up has been renamed to local up. However, the explanation still refers to the old command name: "Do NOT just retry up". This should be updated to "Do NOT just retry local up" to maintain consistency with the new CLI surface.
Suggested change:
| Half-started broker: process alive but `local status` says stopped and `Failed to read broker connection metadata` | `local up` spawned a broker that never finished writing connection metadata (readiness timed out) and was not cleaned up. Do NOT just retry `local up` — it won't reap the orphan. `pkill -f agent-relay-broker` (or `agent-relay local down --force`), delete `.agentworkforce/relay/`, then `agent-relay local up` clean and `agent-relay local status --wait-for 30` || | Tried to read replies with `local tail` | `local tail` streams broker debug events, not worker messages. Read replies with `check_inbox` / `list_messages` / `get_message_thread` | | ||
| | Worker DM to `broker` fails with `Agent "broker" not found` | Expected — `broker` is the broker's internal routing self-name, not a DM-able agent. Workers must ACK/DONE to `orchestrator` or `general`. Fix the worker task prompt; never instruct "DM the broker" | | ||
| | `local status` says running but `local agent list`/MCP calls return empty or `Failed to query broker session` | The CLI is dialing a **stale/wrong broker** — leftover `.agentworkforce/relay/connection.json` from a prior run on an old port, or a second broker process. `ps aux \| grep -c '[a]gent-relay-broker'` (>1 ⇒ kill extras), compare `.agentworkforce/relay/connection.json` to the actual listening port, then `agent-relay local down --force`, delete `.agentworkforce/relay/`, `agent-relay local up` clean | | ||
| | `Invalid agent token` while broker + workers keep working | The orchestrator shell has an **unresolved `${RELAY_API_KEY}`-style template** being used as a literal key (broker/workers hold real tokens). Ensure the workspace key/token is actually resolved in the orchestrator env | |
There was a problem hiding this comment.
The environment variable for the workspace key has been updated to RELAY_WORKSPACE_KEY (as documented in using-agent-relay/SKILL.md and referenced in the bootstrap flow). However, this troubleshooting entry still references the outdated ${RELAY_API_KEY} template. This should be updated to ${RELAY_WORKSPACE_KEY} to avoid confusion.
Suggested change:
| `Invalid agent token` while broker + workers keep working | The orchestrator shell has an **unresolved `${RELAY_WORKSPACE_KEY}`-style template** being used as a literal key (broker/workers hold real tokens). Ensure the workspace key/token is actually resolved in the orchestrator env |![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7f45c5c7e0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Serve a node definition (advertises its capabilities) | ||
| agent-relay fleet serve ./node.ts |
There was a problem hiding this comment.
On a workspace that has not already enabled fleets (the default), this setup order is backwards: the Agent Relay Fleets docs state the per-workspace fleet_nodes_enabled flag is off by default and must be enabled with agent-relay fleet enable --workspace-key "$RELAY_WORKSPACE_KEY" before serving a node (https://agentrelay.com/docs/fleets). A user following this new snippet from top to bottom will try fleet serve first, then wonder why the node does not register/list; move the enable step before this command.
Useful? React with 👍 / 👎.
| # Register a custom capability (command) on this node | ||
| agent-relay capabilities register <command> |
There was a problem hiding this comment.
This command is not runnable as written: the current Agent Relay CLI reference documents agent-relay capabilities register <command> --description <text> --handler <agent> (https://agentrelay.com/docs/reference-cli#capabilities), so omitting both --description and --handler makes the example fail instead of registering the custom action. Please show the complete form or make clear this is only a placeholder.
Useful? React with 👍 / 👎.
1 participant
Refreshes the two Agent Relay skills so they declaratively describe how Agent Relay works today. Both were rewritten command-by-command against the live
agent-relayCLI (verified via--help) and the CLI source.orchestrating-agent-relay/SKILL.mdagent-relay local: broker startup/teardown/readiness islocal up --background/local down/local status --wait-for/local metrics; top-levelagent-relay statusshows workspace + cloud + broker together.local agent:local agent spawn <provider> --name --task --channels --model, pluslocal agent list,attach --mode view,release. MCP equivalentadd_agent/remove_agent.agent-relay mcp, auto-registered asorchestrator) and reads withcheck_inbox/list_messages/get_message_thread, sends withsend_dm/post_message.local tailis called out as broker debug events only — never the way to read a worker's ACK/DONE.capabilitiesgroups for cross-node coordination..agentworkforce/relay/connection.json.using-agent-relay/SKILL.mdlist_dms.message/channelgroups, the participant read/reply/mark-read surface) vs. broker lifecycle (local), withlocal tailflagged debug-only and the read path pointed atmessage inbox check/message get_thread/mark_read.local up --no-dashboardflag.Cross-cutting
.agentworkforce/relay/(was.agent-relay/).cast.agentrelay.com(removedgateway.relaycast.dev).agent-relay-brokerprocess name unchanged.🤖 Generated with Claude Code