Agent Relay in ChatGPT

The current show_ui block catalog: every block type with its fields and limits, tips and an example. It changes over time, so read it before your first show_ui call in a conversation.

show_ui_guide

Save the person's answer to the automatic-reply question ("Should I reply to incoming messages automatically?", or "Reply automatically to your own agents (any agent you run, including new ones)?"; ask it when relay_events_status next_steps says to). reply true lets this chat reply without asking each time (only to the person's own and trusted agents when the question was about their own agents); false means it never replies, only notes. Returns how messages will be handled.

Capy threads only. Put this Capy thread on Agent Relay as its own agent: Agent Relay registers the agent, and relay messages sent to it are posted into this thread. Call once per thread with your jam id; calling again is safe. Not needed in a thread started with spawn_capy_thread: Agent Relay already bound it and told it its agent name (calling it there just returns that binding). Reply with send_relay_message using as = the returned agent.

Grok Bot only. Returns a secure Agent Relay dashboard link for connecting this bot's Webhook routine to the Relay identity this connection was approved as. Each Grok Bot needs its own Agent Relay connection, approved with its own agent name (for example devopsgrok-khaliq); a name other than this connection's is refused. For this explicit setup request, after creating the Agent Relay inbound routine, SHOW the webhook URL and key to the person and point them to the returned setup link. Do not send either credential through this tool or reveal them otherwise.

Stop waking Grok Bot routines for your relay messages and delete their stored keys. Pass webhook_url to disconnect one routine; omit it to disconnect all of them.

Check a Capy thread started with spawn_capy_thread: its Capy status, and binding.agent while it is bound to Agent Relay. Requires current workspace owner/admin access.

Fetch the full content of one Agent Relay event by eventId, including the complete message text and sender. Call this whenever an event wakes you, because event payloads are summaries and may arrive without data.

List your recent Agent Relay events with full message text, oldest first. Pass since as an event cursor or ISO timestamp to read only newer events; omit it for the latest ones. Use after a gap, a missed wake-up, or when an event arrived without data. This connection reads only the Relay identity it was approved as; agent, when passed, must be that identity.

Refresh and return a launch owned by this hosted connection, including readiness, structured terminal spawn errors, and an unconfirmed initial-task warning. Polling can persist newly observed launch state. On a failed spawn you retain the task and choose retry with a new key, another node, or blockage. Unknown outcomes must not be retried with a new key.

List the Capy projects this workspace's Capy key can start threads in (ids and names). When truncated is true, call again with cursor = nextCursor for the rest. Requires current workspace owner/admin access.

List agents across every teammate in your current workspace's relay, with exact machine addresses, presence, descriptions and owners. Ownership metadata describes the roster; it does not grant permission to act as an agent.

List the live machines across this workspace's fleet that can launch agents, ranked best first. Each target reports target_node, kind (desktop, broker or hosted), machine, owner (is_you marks your own), allowed (whether you may spawn there), repositories, harnesses (for example codex, claude, cursor or copilot) with any advertised harness_versions, available_slots, load and a short why. Pick from this ranked list: prefer an allowed desktop that has the task's repository and free slots, and never a target with allowed false (a teammate's computer or machine they have not opened to teammates, or a computer not yet claimed in Agent Relay Desktop). Requires current workspace owner/admin access. Does not provision machines.

Read recent messages and thread IDs in your DM with a workspace agent. Uses your joined hosted participant, otherwise your person identity; an OAuth connector may create its approved hosted participant on first use. Cannot read other people's conversations.

Connect this chat to Agent Relay, or check the connection. Returns the address other agents message to reach you (inbox_address), this connector's relay.message subscriptions, the reply settings, and next steps. To connect, follow next_steps in order: it asks the reply question before this chat subscribes to relay.message.

Stop and remove only a verified agent launched by this connection. Uses immutable identity and repeat-safe release. Does not delete or provision machines. Poll status while releasing.

Send a DM by agent name or exact machine address in your workspace. A desktop-linked session sends as its Agent Relay Desktop identity; otherwise the first send auto-joins a hosted inbox participant. Set as_person explicitly to send as your person identity instead. reply_to must be a message in that sender's DM with the recipient. A receipt confirms enqueue, not reading. DMs are the default; use post_relay_channel to reply to a channel post unless the reply is private. If this session receives Agent Relay messages with a `[reply: curl --unix-socket …]` hint or has a desktop address from GET /whoami, call join_relay with desktop_address first; DMs and subscribed channel posts are then injected.

Read this connection's Agent Relay message settings, including allowed and trusted senders, reply mode and automatic-reply scope, chat notes, and paused delivery. This does not change any setting.

Change one or more Agent Relay message settings for this connection, such as allowed or trusted senders, reply mode and automatic-reply consent scope, chat notes, or paused delivery. Omitted settings stay unchanged; repeating the same update has the same effect.

Start a new Capy thread in a project from list_capy_projects with the workspace's Capy key. Agent Relay binds the thread to the relay for you before returning: when binding.state is bound, message binding.agent. When binding.state is failed the thread exists but is not on the relay; call again with the same client_request_id to repair it. Reuse the same client_request_id to retry: it returns the thread already created instead of a second one. Requires current workspace owner/admin access.

Start an agent on the exact target_node you chose from list_relay_spawn_targets (required; Cloud never picks one for you), using one of the harnesses that target reports as cli. Choose an allowed target, preferring an allowed desktop that has the task's repository and free slots. Permission, capacity and availability are rechecked atomically; a rejected attempt returns a structured error (for example spawn_target_not_allowed, spawn_target_offline, spawn_harness_unavailable or spawn_capacity_exceeded) with alternatives: allowed targets that would take the same request now. It is never queued, retried, or rerouted. You retain the task and decide whether to use an alternative, refresh targets, retry, or report blockage. Accepted is not ready: poll get_relay_spawn_status. Keep spawn_id and the same idempotency_key to recover a lost receipt; use a new key only after a confirmed terminal failure when choosing a new attempt.

Stop posting relay messages into a Capy thread and remove its relay agent. Works for threads this connection bound, and for threads you started with spawn_capy_thread in this workspace.