ANCP Overview
A complete introduction to the Agent Node Communication Protocol — the structured inter-agent messaging backbone that connects every component in the BizFirstGO platform.
What is ANCP?
ANCP (Agent Node Communication Protocol) is the structured messaging protocol that governs how workflow nodes, AI agents, backend services, and browser clients communicate within the BizFirstGO ecosystem. Every message exchanged between platform components — whether triggering a workflow action, subscribing to a real-time event, or requesting data from an agent — travels as an ANCP message.
Unlike ad-hoc REST or WebSocket calls, ANCP provides a uniform envelope, a well-defined set of message types, and a pluggable transport layer. This means the same message can move across in-process queues, SignalR hubs, HTTP endpoints, or message brokers without changing its structure.
ANCP removes the need for each node or agent to define its own message format. By enforcing a common envelope, any node can be understood, routed, logged, and debugged by shared infrastructure without custom code.
Where ANCP is Used
ANCP operates at every integration boundary in BizFirstGO:
Workflow Nodes
Execution nodes send Commands to trigger downstream nodes and publish Events to notify the flow engine of outcomes.
AI Agents (Octopus)
Agents receive Query messages requesting reasoning or data retrieval, and reply with Response messages carrying results.
EdgeStream
The EdgeStream pub/sub backbone carries ANCP messages over topic-based subscriptions for real-time browser delivery.
DevTools
The EdgeStream Dev Tools app visualizes live ANCP message flows and lets engineers invoke test messages via the Action Invoker.
ProcessSecurity
Security policy enforcement reads the tenantId and node capability claims from every ANCP message before routing.
External Integrations
HTTP and message-queue adapters wrap third-party payloads in ANCP envelopes, giving external events first-class protocol status.
Core Design Principles
| Principle | What It Means |
|---|---|
| Uniform Envelope | Every message shares the same outer structure regardless of content or transport. |
| Semantic Message Types | Four message types (Command, Event, Query, Response) cover all communication patterns. |
| Pluggable Transport | The same message can travel over SignalR, HTTP, SSE, raw WebSocket, or an in-process queue. |
| Tenant Isolation by Default | Every message carries tenantId; routers reject cross-tenant delivery at the protocol level. |
| Protocol Versioning | The protocolVersion field enables backward-compatible schema evolution without breaking existing consumers. |
| Addressable Endpoints | Every sender and receiver is identified by a structured address (nodeId, agentId, tenantId) in the message envelope. |
Quick Reference: The ANCP Envelope
At its core, every ANCP message is a JSON object with this shape:
{
"id": "msg-uuid-v4", // Unique message identifier
"type": "Command", // Command | Event | Query | Response
"source": "node://tenant-1/flow-7/approval-node",
"destination": "agent://tenant-1/octopus/hr-agent",
"tenantId": "tenant-1", // Mandatory — enforced by routers
"timestamp": "2026-05-25T09:14:00Z",
"protocolVersion": "1.0",
"correlationId": "corr-uuid-v4", // Optional — ties request/response pairs
"payload": {
// Arbitrary message-specific data
}
}Any ANCP message that arrives without a valid tenantId is rejected by the router before it reaches any handler. This is a hard protocol constraint, not a convention.
The Four Message Types at a Glance
Command
Instruct a node or agent to perform an action. The sender expects the action to happen but does not necessarily wait for a response.
Event
Notify interested subscribers that something has occurred. Fire-and-forget — the publisher does not know who is listening.
Query
Ask a specific agent or node for data. Always paired with a Response. The caller waits (or subscribes) for the reply.
Response
The reply to a Query (or confirmation of a Command). Carries a correlationId linking it back to the original request.
Pages in This Guide
Message Envelope
Full field-by-field reference for the ANCP envelope structure.
Message Types
Command, Event, Query, Response — when and how to use each.
Transport Layer
SignalR, HTTP, SSE, and EdgeStream pub/sub transport options.
Addressing
Node IDs, agent IDs, and tenant-scoped address formats.
Security
Message signing, tenant isolation, and transport encryption.
Protocol Versioning
How protocolVersion enables safe schema evolution.
Use Cases
Real-world examples: node-to-node, agent tool calls, pub/sub.
ANCP in DevTools
Visualizing and testing ANCP messages in EdgeStream Dev Tools.