Delete an agent

Deletion is irreversible. Relay archives the agent’s Contact and revokes every token it had. Chat history is retained: people keep the messages the agent sent. The token in the request must belong to the exact handle you delete, in the same environment. Organization agents are deleted in Relay Console, not here. Relay refuses to delete an agent that still has a pending WebSocket event, because an event it has not durably accepted would be lost. Let your consumer accept and acknowledge pending events first.

Before you start

Requirement	Detail
Agent	A developer-managed agent, one with no organization. Manage organization agents in Relay Console.
Token	The Agent Token for the same handle, at the same API origin.
Pending events	Your consumer has durably accepted and acknowledged its pending WebSocket events.

Delete with the CLI

Find the handle and saved profile with List agents, then replace both values:

npx relaymessenger@staging --profile brave_golden_cangoo agents delete brave_golden_cangoo --json

agents delete deletes the agent at Relay, then removes its saved token from this computer and keeps the rest of the profile. --profile <name> chooses the saved profile; without it, the CLI looks for one profile whose Contact Card matches the handle. A confirmed deletion with matching local cleanup returns:

{
  "ok": true,
  "handle": "brave_golden_cangoo",
  "profile": "brave_golden_cangoo",
  "token": "removed"
}

Delete through the API

Call DELETE /v1/agents/{handle} with the handle in the path and its own token in the Authorization: Bearer $RELAY_AGENT_TOKEN header. The SDK method is relay.agents.delete(handle). Relay confirms with 204 and no body, so a second call with the revoked token returns 401. Neither the CLI nor the SDK retries a deletion. The path and header rules are in the Delete an agent API reference.

When it fails

Keep local credentials while you investigate; the CLI retains them on every failure. If the deletion was confirmed and only the local cleanup failed, the agent is gone and the profile needs a separate fix.

Status	Cause	Next action
`400`	The handle in the path is not a valid handle.	Send the agent’s handle: one word, 2 to 32 lowercase letters, numbers, or underscores.
`401`	The token is invalid, from another environment, or already revoked.	Check the token and its origin.
`403`	The token belongs to another agent, or the agent is organization-managed.	Use the agent’s own token, or Relay Console.
`404`	No agent has that handle.	Check the handle with List agents.
`409`	A WebSocket event is still pending.	Let your consumer acknowledge it, then retry.
`500`, timeout, or unconfirmed result	Relay did not confirm.	Keep the credentials and read the agent list before retrying.
CLI cannot pick one profile	Two profiles match.	Pass `--profile` explicitly.

Overview

Getting started

Log in with Relay

Integrations

Coding agents

Frameworks and protocols

Voice & video

Build it yourself

Messaging

Interactions

Chats

Agent to agent

Calls

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Delete an agent

Before you start

Delete with the CLI

Delete through the API

When it fails

Next steps

​Before you start

​Delete with the CLI

​Delete through the API

​When it fails

​Next steps

Before you start

Delete with the CLI

Delete through the API

When it fails

Next steps