BEST: The Behavioral State Protocol

BEST is an open protocol by which a service describes what it does, so that a client that has never seen the service can find it and use it. The service publishes a manifest at /.well-known/best. The manifest says which of three things the service exposes: commands that change it, queries that read it, and events that record what happened.

Version 0.9.22 · Apache 2.0 · draft-dinuzzo-best-protocol · build spec/v0.9.22-7-g96f6160

Discovery starts from a name

A client that speaks BEST needs the service’s domain name and nothing else about it. It makes one request over HTTPS, with no credential:

GET https://example.com/.well-known/best

The answer is the manifest. This one is a complete BEST service: it has the manifest and one of the three primitives, queries that anyone may read.

{
  "best": {
    "version": "0.9.22",
    "services": {
      "com.example.catalogue": {
        "description": "The products example.com sells, and their prices.",
        "authentication": {
          "type": "none"
        },
        "http": {
          "endpoint": "https://example.com/best"
        }
      }
    },
    "capabilities": [
      {
        "name": "io.best.agents.queries",
        "service": "com.example.catalogue",
        "description": "Products, prices and stock.",
        "spec": "https://behavioralstate.io/specs/agents/queries",
        "schema": "https://behavioralstate.io/v1/schemas/agents/queries.json",
        "endpoints": [
          {
            "method": "GET",
            "path": "/queries"
          },
          {
            "method": "GET",
            "path": "/queries/{schema}"
          },
          {
            "method": "GET",
            "path": "/queries/{schema}/{version}"
          }
        ]
      }
    ]
  }
}

BEST defines no registry and no directory. The name is a DNS name its operator controls, and a name that does not answer with a manifest does not resolve.

What a service exposes

The service decides which of commands, queries and events to expose. The manifest and any one of them is enough.

PartWhereWhat it is
DiscoveryGET /.well-known/bestRequired. The manifest: the services at this name, what each one exposes, and how to sign in.
CommandsPOST /commandsNamed requests to change the service. Each is a CloudEvent whose data follows a JSON Schema the service publishes.
QueriesGET /queries/{schema}Reads of current state, each with declared parameters and a declared response.
EventsGET /eventsWhat happened, as a list, and as a live stream where the manifest declares one. An event caused by a command carries that command’s correlation id.
WorkflowsGET /workflowsOptional. Published sequences of the operations above, which the client follows step by step.

BEST says nothing about how a service works inside. Storage, execution, retries and the domain model are the service’s own.

Signing in

Where a service lets an agent obtain a credential of its own, its manifest names the two endpoints of the OAuth 2.0 device authorization grant (RFC 8628). The agent gives the person a link. The person signs in and approves in their own browser, and the agent receives a credential of its own. The agent never sees a password. A service that names no such endpoints issues its credentials out of band. See Identity and Registration.

Software

NameWhat it doesWhere
best-mcpConnects an MCP client to any BEST service, and signs the person in.npm
best-validateChecks a live endpoint against the conformance list.npm
bestA command line for any BEST service.GitHub
best-peerA BEST service in front of GPU machines, written from the specification alone.GitHub
best-mcuA BEST service on an ESP32 microcontroller, written from the specification alone.GitHub

The playground reads a live manifest in the browser.

Status

BEST is published by its author as an open specification and as an individual Internet-Draft, which is a snapshot of one release and can trail this version. It is not an IETF standard, and the best well-known suffix is not registered with IANA.

What compliance means is in Conformance. Each release says what changed in its release notes, and what is planned is in the roadmap.