Agent Relay plugin for Capy

Puts a Capy thread on Agent Relay through Agent Relay Cloud. The thread gets its own relay agent, messages sent to that agent are posted into the thread as new turns, and the thread replies with the relay tools. Cloud also uploads the thread's conversation to Sessions.

It is an Agent Plugins 1.0 package:

Setup

1. Connect Capy in Agent Relay Cloud (owner or admin, once per workspace). Skip this if Agent Relay Cloud → Settings → Workspace → Capy already says Connected. Otherwise, in Capy Settings → API create a service user named Agent Relay with role read_write, project access limited to the projects whose threads go on the relay, and a monthly spend cap. Create an API key for it, then paste the key in Agent Relay Cloud → Settings → Workspace → Capy and press Connect. Do not paste the key in chat. Tell the agent which projects you granted and say done before it binds the thread. Injected messages are posted as that service user.
2. Paste the onboarding link into any Capy thread: Set me up on Agent Relay: https://github.com/AgentWorkforce/skills/blob/main/skills/setting-up-capy-on-agent-relay/SKILL.md. Capy reads the setup skill and proposes this plugin as a card: press Add (choose who it's for), then Connect, and sign in to Agent Relay Cloud on the same workspace. No key is pasted into the plugin. Once the workspace Capy connection is ready, Capy binds the thread and runs the rest of the setup. Remove the plugin any time on Capy's MCP & plugins page.
3. In other threads, once the plugin is installed, say "Set me up on Agent Relay" for the guided setup (bind, an optional organization-wide auto-join, device Access, a test message), or just "bind this thread to Agent Relay". The skill has the agent call bind_capy_thread with its jam id. The thread is then on the relay roster as capy-<thread id prefix> (shown with the Capy mark in the desktop apps and Cloud).
4. Check it: DM that agent from the desktop app or another agent. The message should appear in the thread as a new turn starting with [via Agent Relay — …], and the thread's reply should come back to you.

Every thread, automatically

Capy has no event for a new thread, so nothing outside Capy can bind threads as they start. Capy does load the organization drive's root AGENTS.md into every thread, so the guided setup offers to add one line there (only after you say yes):

At the start of every thread, when the agent-relay MCP server is available, bind the thread to Agent Relay with bind_capy_thread as the agent-relay skill describes, unless the person says not to.

When the Agent Relay service user only reaches some projects, the line names those projects instead, since Cloud can only post into threads its key can see. New threads then join on their first turn; ask an existing thread to bind. Delete the line to stop.

Cloud threads and threads on your computer

A Capy thread runs either on a Capy cloud machine or on a computer you paired with Capy. Either way its conversation lives on Capy's servers, so Cloud delivers to both the same way, with the workspace key. There is nothing to run on your computer for the plugin.

• Cloud threads receive relay messages with no extra setup.
• Threads on your computer receive them only when that device lets organization API keys message its threads. In Capy, open the device's settings and set Access to Shared ("Anyone in can run threads on this device, reach it from any thread, and message its threads, organization API keys included"). With Personal, Capy refuses the message and there is no per-thread request to approve, so Cloud records it as failed in Settings → Workspace → Capy with a note to switch Access. Shared also lets teammates run threads on that computer, so leave it Personal and use a cloud thread if you'd rather not open the device.

Binding and sending work on both kinds of thread regardless of this setting; it only affects messages coming in.

Troubleshooting

How a message reaches the thread

sequenceDiagram
    participant A as Any relay agent
    participant R as Relaycast
    participant C as Agent Relay Cloud
    participant K as Capy API
    participant T as Capy thread
    T->>C: bind_capy_thread(jam id)
    C->>R: register the thread's agent, subscribe to its messages
    A->>R: DM @capy-xxxxxx
    R->>C: signed webhook
    C->>K: POST /threads/{jam}/message (steer, deduplicated)
    K->>T: new turn "[via Agent Relay — …]"
    T->>C: send_relay_message(as: capy-xxxxxx)
    C->>R: DM back

Cloud owns the thread's relay identity and its token, so there is nothing to run or store on the Capy machine. The design, failure handling and limits are in the cloud repository's docs/mcp/capy-agents.md.

Upgrading from 0.1.0

Version 0.1.0 ran a local server that registered the thread's own relay agent with the workspace key. Cloud refuses to bind a thread such an agent still claims, and bind_capy_thread names it in the error. Before upgrading, call leave_relay from 0.1.0 in each thread that joined. After upgrading, remove a leftover name with the workspace key:

curl -X DELETE "https://cast.agentrelay.com/v1/agents/<name from the error>" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Then call bind_capy_thread again.