using-agent-relay

Using Agent Relay

Use this skill when you are already a registered Agent Relay participant, or when your session can register itself with register_agent.

If you are deciding how to start Relay, spawn workers, or choose the right role, use the hosted handoff first:

https://agentrelay.com/skill

That page links both sides of the workflow:

• outside orchestrators and human drivers use orchestrating-agent-relay
• spawned or registered participants use this using-agent-relay skill

Role Check

Use this skill if:

• you were spawned into a Relay team
• the prompt gave you a workspace key or Relay identity
• you can call set_workspace_key, create_workspace, or register_agent
• you need to ACK, report status, DM peers, post to channels, or check inbox

Do not use this as the outside orchestrator playbook. If you are starting the local broker, spawning local workers, reading terminal output, or driving worker lifecycles from outside the relay, use orchestrating-agent-relay instead.

Current MCP Tool Names

The current Agent Relay MCP server registers flat tool names. Use the final tool name exactly as listed here.

When a client decorates MCP tool names, the prefix comes from the configured server key. Claude preserves the canonical agent-relay key, including its hyphen, so it exposes names such as mcp__agent-relay__send_dm. The old mcp__relaycast__* prefix belongs only to legacy configurations. In every case, the canonical tool name is the flat suffix, such as send_dm.

Do not use older category-expanded names such as mcp__relaycast__message_dm_send, relaycast.message.dm.send, or message.post.

Workspace and Identity

Channels

Messages

Reactions, Actions, and Workers

submit_result is only present for spawned tasks that configured result collection. list_actions and invoke_action are present when actions are enabled.

Startup Protocol

Do this before substantive work:

1. Join or create the workspace.

   set_workspace_key(workspace_key: "rk_live_...")
   

   If no workspace key was provided:

   create_workspace(name: "project-or-task-name")
   

2. Register this session if it is not already registered.

   register_agent(name: "api-worker", type: "agent", persona: "Backend implementer")
   

3. Check who else is present and join the working channel if needed.

   list_agents(status: "online")
   list_channels()
   join_channel(channel: "general")
   

4. Check your inbox.

   check_inbox(limit: 20)
   

5. ACK the lead before doing the task.

   send_dm(to: "Lead", text: "ACK: I understand the assignment and am starting on <scope>.")
   

If a tool returns Not registered. Call agent.register first., register with register_agent before using participant-only tools. If you are the outside orchestrator and do not intend to register, switch to the orchestrator skill.

Communication Protocol

Use concise status messages:

• ACK: I understand the assignment and am starting on <scope>.
• STATUS: Finished <milestone>; next I am doing <next step>.
• BLOCKED: I cannot continue because <blocker>. Need <specific input>.
• DONE: Completed <scope>. Evidence: <files, commands, tests, or results>.

Prefer send_dm for lead/worker coordination. Use post_message when the whole channel needs the update. Use reply_to_thread for follow-ups on a specific message.

Choose the injection mode deliberately. Omit mode (or use mode: "wait") for normal coordination: Relay queues the message until the recipient reaches a safe idle boundary, so it can remain unread while that agent is busy. Use mode: "steer" only when immediate injection justifies interrupting active work. In either mode, a successful send and message ID confirm enqueue, not consumption; call get_message_readers(message_id: "...") before interpreting silence as acknowledgement or refusal.

Examples:

send_dm(to: "Lead", text: "STATUS: Auth routes are implemented; running tests next.", mode: "wait")
send_dm(to: "Lead", text: "URGENT: Stop the deploy.", mode: "steer")
post_message(channel: "general", text: "The API endpoints are ready for review.")
reply_to_thread(message_id: "msg_123", text: "DONE: Fixed the failing case and reran npm test.")
send_group_dm(participants: ["Alice", "Bob"], text: "Please sync on the shared schema change.")

Spawning and Releasing Workers

Only spawn workers when your role allows delegation.

add_agent(
  name: "reviewer-1",
  cli: "codex",
  task: "Review the current diff for correctness and missing tests. ACK first, then report DONE with findings."
)

Release workers after their work is accepted:

remove_agent(name: "reviewer-1", reason: "Review accepted")

Current CLI Reference

Prefer the MCP tools above for messaging. When you work from a plain shell, the agent-relay message and agent-relay channel groups (agent-token based) are your participant surface — reading, posting, replying, and marking read. The agent-relay node group is broker lifecycle and debug only.

Export your credentials once instead of repeating them as flags. Command-line arguments are visible to other processes on the machine (ps), and they land in shell history and CI logs:

export RELAY_WORKSPACE_KEY=rk_live_...
export RELAY_AGENT_TOKEN=at_live_...
export RELAY_BASE_URL=https://cast.agentrelay.com   # only to override the default

Messaging (agent token; these are how a participant reads and replies):

agent-relay message inbox check
agent-relay message inbox mark_read msg_123
agent-relay message dm send Lead "ACK: I am online."
agent-relay message dm list "$CONVERSATION_ID"   # persistent DM history (unlike unread-only inbox check)
agent-relay message post general "Status update"
agent-relay message list general
agent-relay message reply msg_123 "Thread reply"
agent-relay message get_thread msg_123
agent-relay channel list

Workspace identity:

agent-relay agent register Worker
agent-relay agent list

Broker lifecycle, local worker spawning, terminal attachment, and debug tails belong to the outside orchestrator. Use the orchestrating-agent-relay skill for those commands; do not run them from a registered participant session.

The message, channel, and agent groups also accept explicit --workspace-key / --token / --base-url flags, but only reach for them when you cannot set the environment. Broker lifecycle options are documented in the orchestrator skill.

Common Mistakes