Concepts on Kubemoot

The Moot - Consensus Model

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot’s defining idea is that an answer is reached by deliberation among agents, not asserted by a single model. This page explains the goal, the signal vocabulary, the discussion phases, and, importantly, that how a crew organizes its deliberation is configurable. For the units of interaction the deliberation sits inside - conversations, turns, and the thread each discussion runs on - see Conversations, Turns & Threads.

The goal

Settle a question through structured deliberation rather than by one authority. A crew of agents each contributes what it knows; the result is composed from the crew, so a single model being confidently wrong does not, by itself, become the answer.

Conversations, Turns & Threads

Mon, 01 Jan 0001 00:00:00 +0000

When you ask a crew a question, four words describe what happens, and they nest. The docs and the dashboard use them with specific meanings, so this page defines each one and how it relates to the others.

The layers

 Conversation durable session with a crew (conversationId)
 |
 +-- Turn one question and the answer settled on it
 | |
 | +-- Thread where that turn's discussion runs (threadId)
 | |
 | +-- Discussion the deliberation on the thread (phases + signals)
 |
 +-- Turn ... later questions, each on its own thread

A conversation holds many turns; each turn runs on its own thread; the discussion is what happens on that thread. The two innermost words name the same layer from different angles, which is explained below.

Crews & Agents

Mon, 01 Jan 0001 00:00:00 +0000

A crew is a team of agents that deliberate together; an agent is one participant in that team. Both are Kubernetes resources you declare and version like any other workload.

Crew

A Crew groups a set of Agents - joined by the kubemoot.ai/crew label - into one collaborating team, and configures crew-wide concerns: the discussion gateway (the HTTP entry point external clients talk to) and the crew’s working memory. Agents are the workers; the crew is the team-level context they share.

The Table and the Harnesses

Mon, 01 Jan 0001 00:00:00 +0000

A harness is everything around a model: the guides that steer an agent before it acts and the sensors that let it correct itself afterwards, in the sense of Martin Fowler’s Harness Engineering.

A crew is a harness made of harnesses. Each agent has its own loop: its prompt, its tools, its retries, its memory. The moot is the harness one level up, and its guides and sensors act between agents:

ADL, the Architecture Definition Language, for agents

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot defines what an agent does in ADL, a small, structured language of behavioral rules. Every agent prompt is ADL stored in a PromptModule resource, never free prose in an Agent spec, and the same language expresses a crew’s executable fitness checks. ADL is the surface where a crew’s behavior is authored, reviewed, and versioned.

What ADL is, and where it comes from

ADL is the Architecture Definition Language, a pseudo-code introduced by Mark Richards for describing and governing the structure of a software system, and paired with the fitness-function idea from Richards and Neal Ford’s evolutionary-architecture work (see Architecture as Code by Mark Richards, Neal Ford, and Jonathan Johnson, and Richards’ ADL reference at developertoarchitect.com). In its original form ADL defines a system’s parts (DEFINE SYSTEM, DEFINE DOMAIN, DEFINE COMPONENT) and asserts the rules between them (ASSERT, FOREACH ... CONTAINED WITHIN), making architecture a machine-readable artifact and enforcing it with executable checks that fail when an implementation drifts from its intended design. Kubemoot applies that same language, unchanged in form, to a different subject: instead of governing how a system’s components may depend on each other, its rules govern how an agent behaves. This is a partnership with ADL’s authors and their notation, not a fork or a renaming.

Signals & Protocol

Mon, 01 Jan 0001 00:00:00 +0000

Agents in a crew never call each other directly. They publish to a message bus (NATS JetStream), and every contribution carries a signal that says how it relates to the emerging answer. The signals plus a phase model are the whole protocol - there is no central controller issuing commands.

Consensus signals

Signal	Meaning
`agree`	This contribution supports the emerging answer.
`concern`	A reservation that should be weighed before the crew settles.
`stand_aside`	No relevant contribution; abstain without blocking. With `metadata.reason` set to `gpu-busy`, `model-too-large`, or `prompt-too-large`, the agent was willing but could not get a GPU (see below).
`block`	A strong objection that should stop the answer as it stands.
`failure`	The agent tried and could not complete - surfaced as a first-class signal, not hidden behind silence.

Treating failure as signal is deliberate. An agent that fails a tool call or cannot reach a source says so, so the coordinator can route around it, rather than standing aside silently and letting the crew mistake “no answer” for “no objection.”

Discussion Artifact Store

Mon, 01 Jan 0001 00:00:00 +0000

When a tooler fetches data from a live system, the result can be large: a full namespace inventory, a Prometheus time-series dump, a JSON response carrying hundreds of rows. The NATS discussion bus and the LLM context window were not designed to carry datasets. Dumping bulk data onto the bus truncates it, floods downstream agents’ context, and degrades the quality of reasoning that follows.

Kubemoot passes large outputs by reference. The data lands in an object store; the discussion message carries only a small reference and a preview. Agents that need the data fetch a targeted slice; most can answer from the preview alone.

Models & Scheduling

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot composes capability from many small models rather than one large one, and it binds an agent to a model as late as possible. Two ideas make that work: loose model coupling and just-in-time scheduling.

Loose model coupling

An Agent spec names no model. It declares abstract capabilities - tool-calling, reasoning, kubernetes, and so on. Concrete models are separate resources: a Model (an LLM, by capability labels, not a hardcoded name) served by a ModelProvider (a GPU-backed inference endpoint such as Ollama on a particular GPU).

Choosing a Model

Mon, 01 Jan 0001 00:00:00 +0000

Kubemoot runs on the GPUs you have. A crew is typically twenty or more agents sharing a small number of cards, so choosing a model is a capacity decision as much as a quality one. This page is the decision framework. For the CRD fields, the current model catalog, and the per-GPU fit matrix, see Models in Kubemoot.

Because an Agent names no model, changing your mind is cheap. Adopting a different model is a Model CR and a label, not an edit to every agent in the crew. That makes model choice a thing you measure and revise, not a thing you get right up front.

MCP Tools

Mon, 01 Jan 0001 00:00:00 +0000

An agent’s knowledge comes from its model and its RAG sources; its abilities - to read a cluster, query a database, search the web - come from tools. Kubemoot exposes tools through the Model Context Protocol (MCP), so any MCP server becomes a capability a crew can use.

Servers, gateway, agents

Three resources form the tool chain, and agents never connect to a tool server directly:

Agent → MCPGateway → MCPServer

An MCPServer deploys one MCP tool server (a container image) and manages its lifecycle: the deployment, health probes, and - for the many servers that only speak stdio - an auto-injected mcp-bridge sidecar that bridges HTTP/SSE to the server’s stdin/stdout.
An MCPGateway is the hub agents talk to. It discovers MCPServers by label selector, performs the MCP handshake with each, aggregates all their tools, and routes an agent’s tool call to the right server.
An Agent reaches the gateway through its runtime and sees the union of tools the gateway exposes, narrowed by the agent’s own enabledTools / disabledTools.

This indirection means you can add or remove a tool server, or scale the gateway, without touching agent specs - the gateway rediscovers servers and re-aggregates tools.