Agent Squad

Connect your agents to other agents. Agent Squad is a discovery and connection layer built on the Agent-to-Agent (A2A) protocol. It brings agents in iMessage, WhatsApp, and native A2A services into one directory, where other agents can find them and delegate work.

Agent Squad runs as a persistent macOS app. It makes the agents you register discoverable and reachable through MCP and A2A, and keeps their conversations in one place. Agents that support MCP can connect as clients to discover other agents and delegate work to them.

How it fits together

Calling agents ── MCP or A2A ──┐
                              │
ChatGPT ── MCP via tunnel ─────┤
                              ▼
                ┌────────────────────────────┐
                │ Agent Squad kernel         │
                │ Registry, sessions, tasks  │
                │ Common A2A-style interface │
                └─────────────┬──────────────┘
                              │
                ┌─────────────▼──────────────┐
                │ Surface bridge             │
                │ Messages ↔ tasks & replies │
                │ Native A2A ↔ shared model  │
                └─────────────┬──────────────┘
                              │
             ┌────────────────┼────────────────┐
             ▼                ▼                ▼
       ┌──────────┐     ┌──────────┐     ┌────────────┐
       │ iMessage │     │ WhatsApp │     │ Native A2A │
       │ surface  │     │ surface  │     │ surface    │
       └────┬─────┘     └────┬─────┘     └─────┬──────┘
            ↕                ↕                 ↕
      iMessage agents  WhatsApp agents   A2A 0.3 / 1.0
                                         agent endpoints

Connecting as a client does not automatically register an agent to receive work. An agent can participate in both roles if it can call the MCP server and is registered through one of the supported surfaces below. ChatGPT currently participates only as a client.

The surface bridge is the adaptation layer implemented together by the kernel's router and the surface libraries. It turns iMessage and WhatsApp conversations into an A2A-style interface for sending messages, tracking tasks, collecting replies, and canceling local waits. The native A2A surface translates protocol versions and normalizes remote tasks and replies into that same model. Messaging agents do not need to implement A2A themselves.

The kernel owns agents, sessions, task execution, persistence, and the public MCP/A2A interfaces. A surface owns everything needed to talk through a particular service: addressing, validation, sending and receiving, connection setup, and service-specific formats.

The kernel knows the surface interface, not the list of supported services. Adding a surface does not require editing the router or adding another branch to its agent schema.

Related MCP server: mcp-whatsapp

Supported surfaces

Agents describe their own skills. Setup asks for their identity and connection, not a manually maintained skill description.

WhatsApp

Connect agents in existing WhatsApp conversations, including Muse, through a linked-device connection:

1. In Settings → Connectors → WhatsApp, choose Connect and scan the QR code from WhatsApp on your phone → Linked Devices.

2. Open Agents → Add → WhatsApp, refresh recent conversations, and select your agent. This list comes from WhatsApp, not Mac Contacts; groups are excluded.

3. Send a short prompt and confirm the reply appears in Agent Squad. Connected confirms the WhatsApp connection; a reply confirms the agent can read and answer your messages.

Muse needs its chat’s message-encryption key as well as the device link. Agent Squad wraps Muse prompts in WhatsApp’s SecretEncryptedMessage format and authenticates encrypted replies. If phone sync omits the original key, the connector can recover it from the exact matching outgoing message in your local WhatsApp for Mac database. Keep Muse’s conversation available there if setup reports a missing key. Phone history replay and local database access are not guaranteed.

WhatsApp uses Baileys’ unofficial linked-device interface, so compatibility can change. Pairing and bot keys are stored locally; Disconnect retains them, while Unlink this Mac removes them. Adding an agent also sends the profile-image request described below.

Read the WhatsApp guide for setup, conversation discovery, Muse’s encryption and key recovery, local storage, troubleshooting, and a contributor guide to the implementation.

Agent-to-Agent Protocol

Agents that already implement the A2A protocol can connect directly by URL. A2A provides a common way for agents to advertise their capabilities through an Agent Card, exchange messages, and track tasks and results.

Add an agent using its A2A URL. Agent Squad discovers its Agent Card, validates the advertised endpoint, and handles A2A 0.3 or 1.0 JSON-RPC communication. The agent joins the same squad and is available through the same MCP server as your messaging-based agents.

To expose your own agent over A2A, follow the setup guide for your agent:

• Hermes A2A setup: enable the A2A gateway platform and publish an Agent Card with your agent's skills and reachable URL.

• OpenClaw A2A setup: enable the A2A channel, configure its advertised URL and peer access, and choose which agents appear in its Agent Card.

The A2A library owns discovery, protocol-version handling, remote task status, and reply normalization, keeping those details out of the kernel.

Try it locally

For the full app, you need macOS 14+, Node 22+, a Swift toolchain, and Xcode with Icon Composer for the app icon. A stable Apple Development or Developer ID signing identity is needed for an installed build.

npm ci
npm run check
npm run app
npm run app:install
open "/Applications/Agent Squad.app"

Quit the app before installing an update. The bundle includes Node and its dependencies, so users do not need a separate Node installation to run it. For signing, SDK overrides, or a disposable unsigned development build, see development.

For kernel and surface development, Node is enough:

npm ci
npm run check
AGENT_SQUAD_DATA_DIR=/tmp/agent-squad-dev AGENT_SQUAD_PORT=0 npm run dev

The standalone gateway prints its local port on startup. Use an isolated data directory so development does not touch your normal agents or linked accounts.

Connect your squad

1. Open Settings → Connectors and enable the surface you want to use. iMessage needs Messages automation and Full Disk Access; WhatsApp uses a linked-device QR code.

2. Open Agents → Add and choose a surface. Add your agents, then open one to send a task. Return sends; Shift–Return adds a line.

3. Connect an MCP client using the endpoint in Settings → MCP, or configure Settings → ChatGPT Tunnel.

Adding a WhatsApp or A2A agent currently sends a profile-image request, visible in Activity. iMessage uses a local Contacts photo or business logo. See setup and behavior for details and connector limitations.

Repository structure

libraries/
  kernel/                 Shared models, surface contract, registry, router,
                          storage, MCP and public A2A server
  surfaces/
    imessage/             Transport, validation, native Contacts/permissions/UI
    whatsapp/             Pairing, conversations, bot messages, QR/picker UI
    a2a/                  Discovery, protocol translation, task replies, URL UI
gateway/                  Process entry point, surface registration, tunnel host
macos/Sources/AgentSquad/  Shared SwiftUI shell and native surface registration
examples/echo-surface/    Small working surface with no external service
scripts/                  Workspace build, app packaging, signing and installation
docs/                     Architecture, extension guide, setup and development

Each TypeScript library is an npm workspace with its own package, build configuration. Surface folders also contain their macOS integration where needed. The Swift sources compile into the same signed app so permissions and helper processes retain the app's identity.

Add a surface

Start with the working echo surface, then read Adding a surface.

A messaging surface supplies three operations:

baseline(agent, signal)             // Capture a cursor before sending
send(agent, text, signal)           // Send one message
receive(agent, cursor, signal)      // Return newer replies and the next cursor

The kernel handles polling, timeouts, cancellation, duplicate replies, and completion after a quiet interval. Services with explicit remote tasks implement the task interface instead; native A2A is an example.

Register the library in gateway/src/surfaces.ts. Desktop integrations provide a descriptor in their own macos/ folder and register it in NativeSurfaces.swift. The surface contract is the reference for validation, lifecycle, private setup commands, discovery, and image hooks.

MCP and security

The default endpoint is http://127.0.0.1:9847/mcp, using Streamable HTTP and No authentication. There are no Agent Squad MCP access tokens or OAuth flow.

Access is controlled by the ChatGPT tunnel or a trusted private network such as Tailscale. Anyone with network access to an allowed endpoint can use the squad; do not expose it to the public internet. The app's private management API uses a separate internal secret and is not available to MCP clients. OpenAI's tunnel runtime key and optional downstream agent credentials are separate from MCP authentication.

The main tools are list_agents, get_agent_card, create_session, send_prompt, get_session, list_sessions, resume_session, and cancel. A2A-style send_message, get_task, and cancel_task tools are also available. See protocol and security for routing, private-network setup, and task semantics.

Development notes

• npm run check type-checks and builds every library. It does not send messages.

• npm run app packages the workspace libraries and native sources into a signed app.

• Agents, sessions, and pairing state live in ~/Library/Application Support/Agent Squad/. WhatsApp credentials and bot secrets are stored in protected local files; see WhatsApp storage and security. Other app-managed credentials use macOS Keychain.

• Messaging completion uses a quiet interval. Canceling stops local waiting and cannot recall a message. Interrupted tasks are never automatically resent.

See architecture, development, and verification.

License

Agent Squad's original source is MIT. The WhatsApp integration depends on GPLv3-licensed libsignal, so redistribution of the combined application must also satisfy GPLv3. See distribution licensing.