# How Maka Handles Agent Communication: Protocol, Schema, and Runtime Implementation

> Discover how Maka handles agent communication with a typed protocol, compact binary schema, and efficient runtime implementation for state, commands, and telemetry.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-11

---

**Maka handles agent communication through a typed Agent Graph protocol that uses a compact binary schema to exchange state, commands, and telemetry between the runtime host and executing agents.**

The Apache Maka project implements a dedicated **Agent Graph** protocol to manage how the runtime host communicates with individual agents during task execution. This protocol, defined in the `runtime-host` package, provides a compact binary-compatible schema with strict validation rules to ensure secure and reliable message exchange. Understanding how Maka handles agent communication requires examining the protocol constants, data structures, and decoding processes implemented in the core source files.

## Agent Graph Protocol Fundamentals

The foundation of Maka agent communication resides in [`packages/runtime-host/src/protocol/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/agent-graph.ts), which defines the client-server contract and message boundaries.

### Schema Version and Payload Constraints

The protocol maintains strict versioning and size limitations to ensure compatibility and prevent resource exhaustion. The current **protocol version is fixed at `1`**, defined by the constant `AGENT_GRAPH_CLIENT_SCHEMA_VERSION` at lines 31-34. Additionally, the protocol enforces a **maximum payload size of 48 KB** for all exchanged messages, ensuring that transmissions remain compact and processable within memory constraints.

### Message Types and Operations

Maka categorizes agent communication into three primary message families, enumerated in the `AGENT_GRAPH_OPERATION_SPECS` map near lines 52-69:

- **Query** – Requests for graph state including `agent.graph.query` (full snapshot), `agent.graph.operator.query` (single operator inspection), and `agent.graph.epochs.query` (paginated historical data).
- **Control** – Directive messages such as `agent.graph.stop` to halt execution.
- **Signal** – Asynchronous supervisor signals including `attention` (permission requests) and `terminal` (final status notifications).

## Core Communication Data Structures

The protocol relies on strongly-typed TypeScript interfaces to represent the distributed agent state.

### AgentGraphClientSnapshot

The **`AgentGraphClientSnapshot`** type represents the complete state of a running agent graph at a specific moment. As defined in the protocol file at lines 66-68, this structure exposes session identifiers, the current `orchestrationMode` (`graph` or `swarm`), complete operator lists, edge connections, scheduled work items, and recent activity history. This snapshot serves as the primary data transfer object when the client queries the current system state.

### Operator and Activity Records

Individual agents are represented by **`AgentGraphClientOperator`** structures, which encapsulate operator status, edge connectivity, readiness conditions, and current activations. Complementing this, **`AgentGraphClientActivity`** records provide timestamped logs of specific facets such as messages, tool calls, and permission requests, each accompanied by any relevant supervisor signals. These types are instantiated by decoder functions like `decodeAgentGraphClientSnapshot` and `decodeOperator`.

## Message Validation and Decoding

Security and type safety are enforced through rigorous validation before object construction.

### Runtime Validation Helpers

All inbound messages undergo strict runtime checks for type, size, and identity format before processing. Helper functions including **`requireOpaqueIdentity`**, **`requireCount`**, and **`requireFacet`** enforce the protocol contract, ensuring that malformed or tampered messages cannot propagate through the system. These validators act as a tamper-proof gatekeeper for the communication channel.

### Decoding Entry Points

The protocol exposes specific decoder functions for each message type at lines 54-89. These include **`decodeAgentGraphQueryInput`** for snapshot requests, **`decodeAgentGraphOperatorQueryInput`** for individual operator inspection, and **`decodeAgentGraphStopInput`** for halt commands. Each function validates the raw binary payload before constructing the corresponding typed object.

## Orchestration Modes and Supervisor Interaction

Maka supports distinct execution models and interactive workflows through its signaling system.

### Graph vs Swarm Execution

The protocol supports two **orchestration modes** indicated by the `orchestrationMode` field in `AgentGraphClientSnapshot`. **Graph mode** executes agents as a classic DAG with dependency-based scheduling, while **Swarm mode** enables dynamic cooperation among multiple agents without strict topological constraints. This distinction determines how the `AgentGraphExecutionCoordinator` schedules and reconciles work.

### Human-in-the-Loop Signaling

When operators require human intervention, they emit **`SupervisorSignal`** structures of kind `attention` (defined at lines 24-33). These signals carry reasons such as `permission_request` or `user_question`, prompting the client UI to surface interactive prompts. Upon user response, the client transmits an **`AgentGraphClientControlDecision`** back to the host, which the coordinator applies to update the graph state accordingly.

## Runtime Host Coordination

The **Agent Graph Execution Coordinator**, implemented in [`packages/runtime-host/src/server/agent-graph-execution-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-execution-coordinator.ts), serves as the central nervous system for agent communication. This component consumes decoded snapshots from the protocol layer, schedules work according to the current orchestration mode, reconciles topology changes, and forwards control decisions back to individual agents. The coordinator interacts directly with the protocol through the exported `AGENT_GRAPH_OPERATION_SPECS` constants.

## Practical Implementation Examples

The following examples demonstrate how to interact with the Maka agent communication protocol from client code.

To query the current graph snapshot from a running session:

```typescript
import { client } from '@maka/runtime-host';
import { AGENT_GRAPH_OPERATION_SPECS } from '@maka/runtime-host/protocol/agent-graph';

async function getGraphSnapshot(sessionId: string) {
  const input = { rootSessionId: sessionId };
  const { result } = await client.call(
    'agent.graph.query',
    AGENT_GRAPH_OPERATION_SPECS['agent.graph.query'],
    input,
  );
  // `result` is an `AgentGraphClientSnapshot`
  console.log('Graph status:', result.status);
  console.log('Operators count:', result.operators.length);
}

```

To handle permission requests from an agent:

```typescript
import { decodeSignal } from '@maka/runtime-host/protocol/agent-graph';

function handleActivity(activity: AgentGraphClientActivity) {
  activity.signals.forEach(sig => {
    if (sig.kind === 'attention' && sig.reason === 'permission_request') {
      // Show UI prompt to user, then send a control decision back
      requestUserPermission(activity).then(allowed => {
        client.sendControlDecision({
          updateId: generateUuid(),
          revision: activity.run.turnId, // example revision
          committedAt: Date.now(),
          source: activity.run,
          addedWorkIds: [],
          stoppedTargetIds: [],
          selectedResultIds: [],
          // attach the user's decision in a separate field per protocol design
        });
      });
    }
  });
}

```

## Summary

- Maka agent communication relies on a **binary-compatible Agent Graph protocol** with a fixed schema version and 48 KB payload limit, defined in [`packages/runtime-host/src/protocol/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/agent-graph.ts).
- The protocol supports **Query**, **Control**, and **Signal** message types, with strict validation through helpers like `requireOpaqueIdentity` and `requireFacet`.
- Core structures **`AgentGraphClientSnapshot`**, **`AgentGraphClientOperator`**, and **`AgentGraphClientActivity`** provide typed representations of distributed state and history.
- **Graph mode** and **Swarm mode** offer distinct orchestration strategies, while **`SupervisorSignal`** with kind `attention` enables human-in-the-loop workflows.
- The **`AgentGraphExecutionCoordinator`** manages the runtime lifecycle, consuming protocol messages and reconciling system state.

## Frequently Asked Questions

### What is the maximum message size for Maka agent communication?

The Maka Agent Graph protocol enforces a **maximum payload size of 48 KB** for all messages between the runtime host and agents. This limit is hardcoded alongside the schema version constant `AGENT_GRAPH_CLIENT_SCHEMA_VERSION` at lines 31-34 of [`packages/runtime-host/src/protocol/agent-graph.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/agent-graph.ts), ensuring that network transmissions and memory allocations remain bounded and predictable.

### How does Maka validate incoming agent messages?

Maka validates all inbound messages through strict runtime checks implemented in the protocol layer. Helper functions such as **`requireOpaqueIdentity`**, **`requireCount`**, and **`requireFacet`** enforce type safety, size constraints, and identity format requirements before the decoding functions (`decodeAgentGraphQueryInput`, `decodeAgentGraphOperatorQueryInput`, etc.) construct typed objects. This validation pipeline prevents malformed data from reaching the execution coordinator.

### What is the difference between Graph mode and Swarm mode in Maka?

**Graph mode** organizes agents as a Directed Acyclic Graph (DAG) with explicit dependencies and topological scheduling, while **Swarm mode** allows multiple agents to cooperate dynamically without strict dependency constraints. The active mode is indicated by the `orchestrationMode` field in `AgentGraphClientSnapshot` (lines 66-68) and determines how the `AgentGraphExecutionCoordinator` schedules work and reconciles state changes.

### How does Maka handle human permission requests during agent execution?

When an agent requires human input, it emits a **`SupervisorSignal`** with kind `attention` and reason `permission_request`. The client UI detects these signals in the `AgentGraphClientActivity` stream and surfaces an interactive prompt. Once the user responds, the client sends an **`AgentGraphClientControlDecision`** back to the runtime host, which applies the decision to the agent graph state through the execution coordinator.