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.
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.
| Part | Where | What it is |
|---|---|---|
| Discovery | GET /.well-known/best | Required. The manifest: the services at this name, what each one exposes, and how to sign in. |
| Commands | POST /commands | Named requests to change the service. Each is a CloudEvent whose data follows a JSON Schema the service publishes. |
| Queries | GET /queries/{schema} | Reads of current state, each with declared parameters and a declared response. |
| Events | GET /events | What 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. |
| Workflows | GET /workflows | Optional. 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
| Name | What it does | Where |
|---|---|---|
best-mcp | Connects an MCP client to any BEST service, and signs the person in. | npm |
best-validate | Checks a live endpoint against the conformance list. | npm |
best | A command line for any BEST service. | GitHub |
best-peer | A BEST service in front of GPU machines, written from the specification alone. | GitHub |
best-mcu | A 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.