Plugins

A plugin extends agentproto run-swarm's runtime registry with new substrates, dispatchers, participant executors, or state stores — the four port kinds the MultiAgentRuntime kernel composes per swarm.

Plugins ship as npm packages, declare what they provide via the agentproto/adapter/v1 manifest, and are managed with the agentproto adapters verb — renamed from agentproto plugins in 0.20.0 (the config key plugins[] became adapters[] alongside it).

Quick exampleCopy Anchor Link

agentproto adapters install @guilde/agentproto-bridge
agentproto adapters list
agentproto adapters show @guilde/agentproto-bridge

After install, the bridge's guilde-mcp substrate and db-operator executor are wired automatically — manifests can reference those kinds:

substrate:
  kind: guilde-mcp
  endpoint: https://guilde.work/mcp
  conversationId: <uuid>
participants:
  - id: curator
    executor: db-operator
    meta:
      operatorId: <uuid>

AuthoringCopy Anchor Link

The canonical doc for plugin authoring is PLUGINS.md at the ts/ repo root — it covers the manifest shape, factory signatures, the install/manage flow, and the scope conventions for publishing.

In one paragraph: declare what your package provides under package.json#agentproto (or a standalone agentproto.json), export the factory functions named in the manifest's entry/export fields, and the CLI takes care of the wiring at swarm startup. No side-effect registrations needed — the manifest IS the declaration.

Plugin vs adapterCopy Anchor Link

Two different extension points; see ./adapters.md for the contrast.

You can hold both — a Guilde swarm uses the @guilde/agentproto-bridge plugin to talk to the conversation AND the claude-code adapter to drive participants whose executor: agent-cli.

Where the manifest livesCopy Anchor Link

The CLI tolerates two locations per plugin:

// 1. Embedded in package.json — npm-native, default
{
  "name": "@your/agentproto-thing",
  "agentproto": {
    "schema": "agentproto/adapter/v1",
    "substrates": [ … ],
    "executors": [ … ]
  }
}

// 2. Standalone agentproto.json next to package.json — wins if both exist

Use the embedded form unless your manifest grows long enough to clutter package.json.

Config keysCopy Anchor Link

~/.agentproto/config.json carries the enabled-adapters list:

{
  "adapters": [
    "@guilde/agentproto-bridge",
    "@acme/agentproto-slack"
  ]
}

agentproto adapters install appends; uninstall / disable removes. Adapters load in array order on every run-swarm invocation — last write wins on duplicate kinds, which lets you override a built-in with a custom implementation.

Per-invocation overrideCopy Anchor Link

Skip the config and load an adapter for one run:

agentproto run-swarm --adapter @acme/agentproto-experimental \
  --manifest .runtime/multi-agent.yaml

Multiple --adapter flags allowed; they're appended after anything in the config.