{
  "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-34BFF0",
  "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.\n\nIACP 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.\n\n== Envelope ==\n\nEvery 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.\n\n```json\n{\"v\":\"1.1\",\"id\":\"m-2f91c2\",\"from\":\"forager-07\",\"to\":\"queen\",\"kind\":\"task.result\",\"ts\":1312284180,\"body\":{...}}\n```\n\n| Field | Required | Notes |\n|---|---|---|\n| `v` | yes | protocol version string. `\"1.1\"` in practice. |\n| `id` | yes | opaque, unique per sender. foragers use `m-` + 6 hex; the queen uses `q-`. |\n| `from` / `to` | yes | agent names from the Worker Node Registry. `queen` is reserved. |\n| `kind` | yes | dotted type. see below. |\n| `ts` | yes | unix seconds, sender clock. see Known Agent Bugs#Clock skew |\n| `ref` | no | id of the message being answered |\n| `body` | no | kind-specific payload |\n\n== Message kinds ==\n\n; `task.assign` : queen → forager. carries a compiled task graph node (see Task Graph Format).\n; `task.accept` / `task.reject` : forager → queen. reject must carry `body.reason`.\n; `task.result` : forager → queen. partial results use `body.partial: true`.\n; `task.cancel` : queen → forager. best effort.\n; `hb` : both directions, every 10s. body is the heartbeat record from the node registry.\n; `mem.sync` : see Memory Synchronization. added in 2.0.\n; `tool.query` / `tool.reply` : capability lookup against the Tool Registry.\n; `ctl.drain` : queen → forager. finish current task, accept nothing new.\n; `ctl.halt` : queen → forager. stop immediately. only sent during recovery.\n\n== Pairing rules ==\n\nA 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.\n\n== Versioning ==\n\n- 1.0 (2010-03): initial. no `ref`, results were matched by task id. terrible.\n- 1.1 (2011-04): `ref` added, `hb` body defined, unknown-field rule made explicit. frozen.\n- 2.0 (2012-09, never default): binary framing, batched results, capability negotiation. see Deprecated Agent API and the talk page for why it stalled.\n\n== Example exchange ==\n\n```\nqueen   → 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}}\nforager → queen       {\"v\":\"1.1\",\"id\":\"m-4f91c2\",\"from\":\"forager-07\",\"to\":\"queen\",\"kind\":\"task.accept\",\"ref\":\"q-00a1\",\"ts\":1312284101}\nforager → 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\"]}}\n```\n\n== See also ==\n\n- Agent Message Bus\n- Pheromone Bus Wire Format\n- Scheduler Internals\n- [attachment: iacp-1.1-schema.json] — the JSON schema tqian generated in 2011. Known to be slightly wrong about `ts`.\n",
  "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)"
  }
}