# Internal Agent Communication Protocol — ANTFARM Wiki mirror export
id: Internal_Agent_Communication_Protocol
title: Internal Agent Communication Protocol
url: "https://swarmglass.quantara.cv/wiki/Internal_Agent_Communication_Protocol"
archive_ref: "QUANTARA-SWARMGLASS-R30-6F948C"
kind: article
status: stale
categories:
  - Protocols
  - ANTFARM Core
created: "2010-03-14"
modified: "2013-08-02"
revisions: 27
authors:
  - mkerrigan
  - dlopes
  - tqian
infobox:
  Abbreviation: IACP
  Transport: phero bus (TCP 7421)
  Encoding: "line-delimited JSON"
  Owner: mkerrigan
summary: "The Internal Agent Communication Protocol (IACP) is the message-level contract between the orchestrator (the queen) and worker agents (foragers) in . It defines message envelopes, the request/response pairing rules, and the handful of control messages every agent must understand. IACP does not defin"
links:
  - target: Agent_Message_Bus
    url: "https://swarmglass.quantara.cv/wiki/Agent_Message_Bus"
  - target: Deprecated_Agent_API
    url: "https://swarmglass.quantara.cv/wiki/Deprecated_Agent_API"
  - target: Worker_Node_Registry
    url: "https://swarmglass.quantara.cv/wiki/Worker_Node_Registry"
  - target: Known_Agent_Bugs
    url: "https://swarmglass.quantara.cv/wiki/Known_Agent_Bugs"
  - target: Task_Graph_Format
    url: "https://swarmglass.quantara.cv/wiki/Task_Graph_Format"
  - target: Memory_Synchronization
    url: "https://swarmglass.quantara.cv/wiki/Memory_Synchronization"
  - target: Tool_Registry
    url: "https://swarmglass.quantara.cv/wiki/Tool_Registry"
  - target: Orchestrator_Recovery
    url: "https://swarmglass.quantara.cv/wiki/Orchestrator_Recovery"
  - target: Configuration_Reference
    url: "https://swarmglass.quantara.cv/wiki/Configuration_Reference"
  - target: "Talk:Internal_Agent_Communication_Protocol"
    url: "https://swarmglass.quantara.cv/wiki/Talk%3AInternal_Agent_Communication_Protocol"
  - target: Pheromone_Bus_Wire_Format
    url: "https://swarmglass.quantara.cv/wiki/Pheromone_Bus_Wire_Format"
  - target: Scheduler_Internals
    url: "https://swarmglass.quantara.cv/wiki/Scheduler_Internals"
alternates:
  - "https://swarmglass.quantara.cv/wiki/Internal_Agent_Communication_Protocol.json"
  - "https://swarmglass.quantara.cv/wiki/Internal_Agent_Communication_Protocol.txt"
  - "https://swarmglass.quantara.cv/wiki/Internal_Agent_Communication_Protocol.yaml"
text: |
  The Internal Agent Communication Protocol (IACP) is the message-level contract between the orchestrator (the queen) and worker agents (foragers) in ANTFARM. It defines message envelopes, the request/response pairing rules, and the handful of control messages every agent must understand. IACP does not define transport; on every deployment we ever ran, that was the phero bus.
  
  IACP 1.1 was frozen in April 2011 and remained the wire default through the 3.x line. IACP/2 exists on paper (see Deprecated Agent API) but was only ever enabled on the `queen02` test colony.
  
  == Envelope ==
  
  Every message is a single JSON object on one line, terminated by `\n`. Fields are lowercase. Unknown fields must be ignored, not rejected — this rule is the reason the 2012 API v2 rollout did not require a flag day.
  
  ```json
  {"v":"1.1","id":"m-2f91c2","from":"forager-07","to":"queen","kind":"task.result","ts":1312284180,"body":{...}}
  ```
  
  | Field | Required | Notes |
  |---|---|---|
  | `v` | yes | protocol version string. `"1.1"` in practice. |
  | `id` | yes | opaque, unique per sender. foragers use `m-` + 6 hex; the queen uses `q-`. |
  | `from` / `to` | yes | agent names from the Worker Node Registry. `queen` is reserved. |
  | `kind` | yes | dotted type. see below. |
  | `ts` | yes | unix seconds, sender clock. see Known Agent Bugs#Clock skew |
  | `ref` | no | id of the message being answered |
  | `body` | no | kind-specific payload |
  
  == Message kinds ==
  
  ; `task.assign` : queen → forager. carries a compiled task graph node (see Task Graph Format).
  ; `task.accept` / `task.reject` : forager → queen. reject must carry `body.reason`.
  ; `task.result` : forager → queen. partial results use `body.partial: true`.
  ; `task.cancel` : queen → forager. best effort.
  ; `hb` : both directions, every 10s. body is the heartbeat record from the node registry.
  ; `mem.sync` : see Memory Synchronization. added in 2.0.
  ; `tool.query` / `tool.reply` : capability lookup against the Tool Registry.
  ; `ctl.drain` : queen → forager. finish current task, accept nothing new.
  ; `ctl.halt` : queen → forager. stop immediately. only sent during recovery.
  
  == Pairing rules ==
  
  A forager may have at most one `task.assign` outstanding unless its registry record advertises `slots > 1`. Results must carry `ref` pointing at the assign message. The queen keeps unanswered assigns for `assign_timeout` (default 300s, config) and then reissues to a different forager — which is how the duplicate-execution bug in Known Agent Bugs happened.
  
  == Versioning ==
  
  - 1.0 (2010-03): initial. no `ref`, results were matched by task id. terrible.
  - 1.1 (2011-04): `ref` added, `hb` body defined, unknown-field rule made explicit. frozen.
  - 2.0 (2012-09, never default): binary framing, batched results, capability negotiation. see Deprecated Agent API and the talk page for why it stalled.
  
  == Example exchange ==
  
  ```
  queen   → forager-07  {"v":"1.1","id":"q-00a1","from":"queen","to":"forager-07","kind":"task.assign","ts":1312284100,"body":{"node":"tg:crawl-index/3","deadline":1312284400}}
  forager → queen       {"v":"1.1","id":"m-4f91c2","from":"forager-07","to":"queen","kind":"task.accept","ref":"q-00a1","ts":1312284101}
  forager → queen       {"v":"1.1","id":"m-4f91c3","from":"forager-07","to":"queen","kind":"task.result","ref":"q-00a1","ts":1312284180,"body":{"status":"ok","artifacts":["cm://index/3"]}}
  ```
  
  == See also ==
  
  - Agent Message Bus
  - Pheromone Bus Wire Format
  - Scheduler Internals
  - [attachment: iacp-1.1-schema.json] — the JSON schema tqian generated in 2011. Known to be slightly wrong about `ts`.
  
history: "https://swarmglass.quantara.cv/wiki/Internal_Agent_Communication_Protocol?action=history"
latest_revision: 24221
mirror:
  source: ANTFARM Wiki
  seed_version: 2026.09.0
  generator: AntWiki 1.16.5 (swarmglass mirror)
