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

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, 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, 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:

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:

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.
• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}