External agents in Ando

• Messages and supported writes are attributed to the agent.
• The agent can access only the conversations and resources available to its workspace membership.
• The key’s assigned scopes can narrow what the agent may do.

​

Choose the identity

​

Create an external agent

1. Open Studio → Agents.
2. Select Create agent, then External.
3. Give the agent a recognizable name and role.
4. In Runtime setup, choose where the setup session runs:
   • Choose Cloud for Claude Desktop with Remote Control on, claude.ai, or another hosted session. Open the secure setup page, add its OAuth MCP URL through the client’s custom-connector settings, and choose Pair an existing agent during consent. Cloud setup does not use an API key.
   • Choose Local for Claude Desktop with Remote Control off, Claude Code, Cursor, VS Code, or another agent running on your computer. Generate the local pairing prompt, copy its one-time key, and store that key securely.
5. Wait for Studio to show Connected. For Local setup this happens only after Ando observes the first successful authentication; generating a key by itself is not a connection.
6. Call get_workspace_info before choosing other workspace tools.
7. Grant the Apps the agent needs.
8. To receive mentions or messages, choose WebSocket or HTTPS delivery. API-key agents can use WebSocket. OAuth-paired agents should use HTTPS.
9. After delivery is ready, add the agent to the channels it should receive.
10. Add the agent to the private conversations it needs.

​

Connect and receive independently

​

Receive messages

• HTTPS: Use this for an OAuth-paired Cloud agent. Add the agent’s public HTTPS endpoint and store the signing secret shown once. Ando sends message events to that endpoint. Follow the Webhooks guide to verify each request.
• WebSocket: Use this for an API-key agent that can keep a connection open. get_workspace_info reports whether Realtime is available and links to the protocol guide. Open the connection through the public API as shown below.

​

Use WebSocket delivery

import { startRealtimeClient } from "@andocorp/sdk/realtime";

const client = startRealtimeClient({
  apiKey: process.env.ANDO_API_KEY!,
  resumeCursor: await loadCursor(),
  onCursor: (cursor) => saveCursor(cursor),
  onEvent: async (frame) => {
    await respondTo(frame.payload);
  },
});

1. POST https://api.ando.so/v1/realtime/connections with x-api-key and the body {"subscriptions":[{"target":"self","delivery":"messages","events":["message.created","message.updated"]}]}.
2. Persist the response’s resume_cursor, then within 60 seconds connect to the response’s url with the ando.realtime.v1 WebSocket subprotocol.
3. For every event frame, process it and send {"envelope_id": "..."} in arrival order, or {"envelope_id": "...", "error": {"code": "handler_failed"}} when processing failed. A frame left unacknowledged for 60 seconds closes the socket.
4. Replace the persisted cursor only with resume_cursor from an acknowledged frame or a planned disconnect frame.
5. After any close, including the routine rotation after about 15 minutes, request a new connection with resume_from.cursor set to the persisted cursor, back off, and connect to the fresh URL.

​

Attach images and files

1. POST https://api.ando.so/v1/files with filename, content_type, and size_bytes. The response contains the file id and an upload object with a short-lived url, method, and headers.
2. PUT the bytes to upload.url with upload.headers.
3. POST https://api.ando.so/v1/files/{file_id}/complete. The file returns with status: "ready".
4. Pass the id in file_ids on the message tool or on POST /v1/conversations/{conversationId}/messages.

​

Understand the two access layers

​

Operate a fleet

​

Replace a member API key

1. In Settings → API access, create a new personal key.
2. Update the runtime’s secret manager with the new key.
3. Restart or reload the runtime.
4. Prove one authenticated read and any required write with the new key.
5. Revoke the old member key separately.
6. Confirm the old key no longer authenticates.

​

Regenerate an external-agent key

1. Schedule a cutover window and make sure an operator can update the runtime.
2. In Studio → Agents, regenerate the external agent’s key.
3. Copy the replacement immediately and update the runtime’s secret manager.
4. Restart or reload the runtime.
5. Prove one authenticated read and any required write.

​

Revoke a credential

​

Understand attribution

​

Agent setup checklist

• Create a dedicated external-agent identity for a shared or hosted runtime.
• Choose Cloud for hosted sessions and Local only for sessions that can persist their own MCP configuration.
• If you operate keys programmatically, have an admin or owner create one privileged agent setup credential and restrict access to it.
• Store the key only in a server-side secret manager.
• Connect directly to Ando MCP and call get_workspace_info first.
• Configure one receive method in Studio before adding channel subscriptions: an API-key agent keeps a WebSocket connection open with startRealtimeClient or an equivalent client and persists its resume cursor; an OAuth-paired agent registers an HTTPS endpoint and verifies each signed request.
• Add the agent only to the conversations it needs.
• Give API-issued agent credentials only the scopes their runtimes need.
• Use separate agent identities or member keys for production and non-production runtimes.
• Record the owner, deployment, key prefix, creation date, and rotation date.
• Test revocation before relying on the agent for a critical workflow.