Agentic Node
Communication Protocol

01 Overview

The Agentic Node Communication Protocol (ANCP) is an open, HTTP-based protocol that defines how autonomous software agents — called nodes — communicate with each other within and across the BizFirst platform. ANCP is the standardized language that allows every node to call, respond to, stream from, and coordinate with every other node, regardless of where they are hosted.

ANCP is not a new wire format. All messages use the platform-standard IEnvelope — the universal BizFirst message container. ANCP adds a metadata extension block (metadata["ncp"]) inside the envelope that carries protocol-specific fields like action names, routing information, and task identifiers.

What ANCP Provides

02 Design Goals

03 IEnvelope — Wire Format

Every ANCP message is a JSON object conforming to the IEnvelope schema. The same schema is used for requests, responses, SSE chunks, task-status envelopes, and error responses.

{
  "meta": {
    "id":           "corr-uuid-here",        // Correlation ID (required)
    "topic":        "ncp:7:42:call",          // Routing topic
    "timestamp":    "2026-03-16T10:30:00Z",   // ISO-8601 UTC
    "nodeProtocol": "ncp",                    // MUST be "ncp" for ANCP messages
    "protocol":     null                      // Transport field — do NOT set to "ncp"
  },
  "body": {
    "data": {
      "metadata": {
        "messageType": {
          "type":    "ncp",
          "subType": "request-reply",          // Message pattern
          "handler": "AncpHandler"
        },
        "source": { "name": "CallerNode", "system": "ANCP" },
        "extensions": {
          "ncp": {                             // AncpMetadataExtension
            "version":        "1.0",
            "action":         "get-payroll-status",
            "targetNodeId":   42,
            "targetTenantId": 7,
            "targetRole":     "default",
            "callerNodeId":   55,
            "callerTenantId": 8,
            "callerDid":      "did:bizfirst:tenant8:node:55"
          }
        }
      },
      "data":  { ... },    // Request payload or response data
      "error": null        // AncpError if call failed
    }
  }
}

04 Node Addressing

NodeAddress identifies a target node or node group for an ANCP call. It is immutable, created exclusively through static factory methods, and carries exactly one active addressing mode per instance.

// NodeId — same server, same tenant
NodeAddress.FromNodeId(tenantId: 7, nodeId: 42)

// ResId — cross-server, same tenant
NodeAddress.FromResId(tenantId: 7, resId: Guid.Parse("..."))

// DID — cross-tenant, identity-based
NodeAddress.FromDid("did:bizfirst:tenant7:node:42")

// EVM address — blockchain identity
NodeAddress.FromEvmAddress("0xAbCd...1234", chainId: 137)

// Node group (round-robin by default)
NodeAddress.FromNodeGroupId(tenantId: 7, groupId: 10)
NodeAddress.FromNodeGroupResId(tenantId: 7, groupResId: Guid.Parse("..."))

// OperateID — federated operator identity
NodeAddress.FromOperateId("op:acme:billing-engine-1")

// Direct URL — bypass registry entirely
NodeAddress.FromDirectUrl("https://partner.example.com", nodeId: 42, tenantId: 7)

05 Message Patterns

POST /ncp/nodes/42/invoke
X-Ancp-Version: 1.0
Authorization: Bearer {jwt}

{
  "meta": { "id": "corr-001", "nodeProtocol": "ncp", "timestamp": "..." },
  "body": { "data": {
    "metadata": {
      "messageType": { "type": "ncp", "subType": "fire-and-forget" },
      "extensions": { "ncp": { "version": "1.0", "action": "trigger-recalc" } }
    },
    "data": { "employeeId": 123 }
  }}
}

HTTP/1.1 202 Accepted
(no body)

POST /ncp/nodes/42/invoke
X-Ancp-Version: 1.0
Authorization: Bearer {jwt}

{
  "meta": { "id": "corr-002", "nodeProtocol": "ncp", "timestamp": "..." },
  "body": { "data": {
    "metadata": {
      "messageType": { "type": "ncp", "subType": "request-reply" },
      "extensions": { "ncp": { "version": "1.0", "action": "get-payroll-status",
        "callerNodeId": 55, "callerTenantId": 8 } }
    },
    "data": { "employeeId": 123 }
  }}
}

HTTP/1.1 200 OK
X-Ancp-Version: 1.0
X-Ancp-Correlation-Id: corr-002
X-Ancp-Node-Id: 42

{
  "meta": { "id": "corr-002", "nodeProtocol": "ncp", ... },
  "body": { "data": {
    "metadata": {
      "messageType": { "type": "ncp", "subType": "response" },
      "extensions": { "ncp": { "version": "1.0", "action": "get-payroll-status",
        "receiverNodeId": 42, "durationMs": 12 } }
    },
    "data": { "employeeId": 123, "status": "Active", "lastRunAt": "2026-03-01T00:00:00Z" }
  }}
}

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
X-Ancp-Version: 1.0

event: chunk
data: {"meta":{"id":"corr-003","nodeProtocol":"ncp",...},"body":{"data":{"metadata":{"messageType":{"subType":"stream-chunk"},"extensions":{"ncp":{"sequence":1}}},"data":{"department":"Engineering","total":142000}}}}

event: chunk
data: {"meta":{"id":"corr-003","nodeProtocol":"ncp",...},"body":{"data":{"metadata":{"messageType":{"subType":"stream-chunk"},"extensions":{"ncp":{"sequence":2}}},"data":{"department":"Finance","total":89000}}}}

event: complete
data: {"meta":{"id":"corr-003","nodeProtocol":"ncp",...},"body":{"data":{"metadata":{"messageType":{"subType":"stream-complete"},"extensions":{"ncp":{"sequence":2,"durationMs":847}}}}}}

HTTP/1.1 202 Accepted
Location: /ncp/nodes/42/tasks/task-a1b2c3d4

{
  "meta": { "id": "corr-004", "nodeProtocol": "ncp", ... },
  "body": { "data": {
    "metadata": {
      "messageType": { "subType": "task-accepted" },
      "extensions": { "ncp": { "taskId": "task-a1b2c3d4", "taskState": "pending",
        "taskStatusUrl": "/ncp/nodes/42/tasks/task-a1b2c3d4" } }
    }
  }}
}

{
  "meta": { ... },
  "body": { "data": {
    "metadata": {
      "messageType": { "subType": "task-status" },
      "extensions": { "ncp": { "taskId": "task-a1b2c3d4", "taskState": "running",
        "taskProgress": 42 } }
    }
  }}
}

06 HTTP Transport

07 Authentication

The receiver validates credentials in strict priority order: JWT → API-Key → DID Proof. The first matching credential wins. If none match, 401 Unauthorized is returned with no body (for security).

08 AncpClient

The AncpClient is the caller-side API. Register it once as a Singleton and inject IAncpClient wherever you need to call another node.

// Registration
builder.Services.AddAncpClient(opts =>
{
    opts.DefaultTenantId     = 7;
    opts.RegistryBaseUrl     = "https://registry.bizfirst.internal";
    opts.RequestReplyTimeout = TimeSpan.FromSeconds(30);
    opts.Auth = new AncpAuthOptions { BearerToken = myJwtToken };
});

// Fire-and-forget
await _ancpClient.FireAndForgetAsync(
    NodeAddress.FromNodeId(tenantId: 7, nodeId: 42),
    action:  "trigger-recalc",
    payload: new { employeeId = 123 });

// Request-reply
var response = await _ancpClient.InvokeAsync<PayrollStatusResponse>(
    NodeAddress.FromNodeId(7, 42),
    action:  "get-payroll-status",
    payload: new { employeeId = 123 });

// Streaming
await foreach (var chunk in _ancpClient.StreamAsync<PayrollLine>(
    NodeAddress.FromNodeId(7, 42), "stream-payroll-lines", req))
{
    Console.WriteLine(chunk.Department);
}

// Task-start
var handle = await _ancpClient.StartTaskAsync(
    NodeAddress.FromNodeId(7, 42),
    action:  "run-full-payroll",
    payload: new { payrollPeriodId = "2026-03" });

var status = await _ancpClient.GetTaskStatusAsync<PayrollRunResult>(handle);

Endpoint Resolution

AncpClient resolves endpoints in this order:

1. If NodeAddress.Mode == Direct, use the provided URL directly — no registry call.
2. Check AncpEndpointCache (TTL-based, default 5 min). Return cached endpoint if fresh.
3. Call IAncpRegistryClient → GET {registryBaseUrl}/resolve?{queryString}.
4. Cache the result and proceed.

09 IAncpNodeCapability

The IAncpNodeCapability is the receiver-side API. Node authors register action handlers against it in ConfigureAncp(). The capability is injected as the protected Ancp property on BaseNodeExecutor.

protected override void ConfigureAncp(IAncpNodeCapability ncp)
{
    // Request-reply
    ncp.OnInvoke<GetStatusRequest, StatusResponse>(
        "get-status",
        async ctx => await _service.GetStatusAsync(ctx.Payload!.Id));

    // Fire-and-forget
    ncp.OnFireAndForget<TriggerRequest>(
        "trigger",
        ctx => _service.TriggerAsync(ctx.Payload!.Id));

    // Streaming
    ncp.OnStream<StreamRequest, LineItem>(
        "stream-lines",
        ctx => _service.StreamAsync(ctx.Payload!.PeriodId, ctx.CancellationToken));

    // Long-running task
    ncp.OnTask<RunRequest, RunResult>(
        "run-full",
        async (ctx, ct) => await _service.RunAsync(ctx.Payload!.PeriodId, ct));
}

Receiver Pipeline (7 Steps)

10 Registry & Heartbeat

The ANCP Registry is a central service that maps node identities to endpoint URLs. Nodes register themselves at startup via heartbeat and deregister on shutdown. The registry is queried by AncpClient during endpoint resolution.

// Heartbeat payload (POST {registryBaseUrl}/heartbeat)
{
  "nodeId":            42,
  "tenantId":          7,
  "endpoint":          "https://server2.bizfirst.internal/ncp/nodes/42/invoke",
  "resId":             "a1b2c3d4-e5f6-...",
  "did":               "did:bizfirst:tenant7:node:42",
  "supportedPatterns": ["fire-and-forget", "request-reply", "streaming", "task-start"],
  "registeredActions": ["get-payroll-status", "run-full-payroll", "stream-payroll-lines"]
}

11 Discovery Document

When ExposeDiscoveryDocument = true (the default), the receiver exposes a machine-readable capability manifest at GET /.well-known/ncp.json:

{
  "ncpVersion":     "1.0",
  "nodeId":         42,
  "tenantId":       7,
  "did":            "did:bizfirst:tenant7:node:42",
  "autonomousMode": true,
  "aiModel":        "claude-sonnet-4-6",
  "authModes":      ["jwt", "api-key"],
  "systemActions":  ["ancp.ping", "ancp.capabilities", "ancp.negotiate", "ancp.status"],
  "nodes": [
    {
      "nodeId":    42,
      "tenantId":  7,
      "actions": [
        { "name": "get-payroll-status", "pattern": "request-reply",  "requiresAuth": true },
        { "name": "run-full-payroll",   "pattern": "task-start",     "requiresAuth": true },
        { "name": "stream-payroll",     "pattern": "streaming",       "requiresAuth": true }
      ]
    }
  ]
}

12 Observability

Activity Sources

Meter: BizFirst.Ancp

13 Payment Flow

Autonomous nodes can gate access to capabilities behind EVM on-chain payments. The full flow is:

14 DI Registration

Receiver (Node B)

// Program.cs
builder.Services.AddAncpNodeCapability(opts =>
{
    opts.BaseUrl                 = "https://server2.bizfirst.internal";
    opts.ExposeDiscoveryDocument = true;
    opts.Registry.BaseUrl        = "https://registry.bizfirst.internal";
    opts.Registry.HeartbeatIntervalSeconds = 30;
});

app.UseAncp();  // Maps /ncp endpoints and /.well-known/ncp.json

Caller (Node A)

builder.Services.AddAncpClient(opts =>
{
    opts.DefaultTenantId     = 7;
    opts.RegistryBaseUrl     = "https://registry.bizfirst.internal";
    opts.RequestReplyTimeout = TimeSpan.FromSeconds(30);
    opts.StreamingTimeout    = TimeSpan.FromSeconds(300);
});

Registered Services

15 BaseNodeExecutor Integration

ANCP integration is surfaced in BaseNodeExecutor as a partial class (BaseNodeExecutor.Ancp.cs):

public abstract partial class BaseNodeExecutor
{
    // Never null — NullAncpNodeCapability for light nodes
    protected IAncpNodeCapability Ancp { get; private set; } = NullAncpNodeCapability.Instance;

    // Null if AddAncpClient() not registered
    protected IAncpClient? AncpClient { get; private set; }

    // Override to register handlers — called once at startup
    protected virtual void ConfigureAncp(IAncpNodeCapability ncp) { }

    // Called by ProcessEngine infrastructure — do not call directly
    internal void InitializeAncp(IAncpNodeCapability capability, IAncpClient? client);
}

16 Autonomous Nodes

An autonomous node operates independently 24/7. It processes ANCP calls without human intervention, advertises its capabilities, gates access behind payment, and makes outbound calls to other nodes. Autonomous nodes implement all 6 standard system actions.

System Actions

Registering System Actions

ncp.AddSystemActions(nodeEntry, new AncpSystemActionsConfig
{
    Version      = "2.5.1",
    Environment  = "production",
    IsAutonomous = true,
    AiModel      = "claude-sonnet-4-6",
    PriceList = [
        new AncpPriceDef { Action = "run-payroll", Pattern = "task-start",  PriceUsdc = 10.00m },
        new AncpPriceDef { Action = "stream-report", Pattern = "streaming", PriceUsdc = 2.50m  }
    ],
    Payment = new AncpPaymentServiceConfig
    {
        EvmAddress     = "0xAbCd1234...",
        ChainId        = 137,
        PreferredToken = "USDC"
    }
});

17 Testing

FakeAncpTransport

Replace the real HTTP transport in tests. No HTTP calls are made.

var fakeTransport = new FakeAncpTransport();

// Setup responses
fakeTransport.SetupResponse(
    urlPattern: "/invoke",
    responseData: new PayrollStatusResponse { Status = "Active" });

fakeTransport.SetupStream(
    urlPattern: "/invoke",
    chunks: [new PayrollLine { Dept = "Eng", Total = 142_000 }]);

fakeTransport.SetupError(
    urlPattern: "/invoke",
    error: new HttpRequestException("Network failure"));

// After the test
Assert.Single(fakeTransport.CapturedRequests);
Assert.Contains("get-payroll-status", fakeTransport.CapturedRequests[0].Body);

Testing Action Handlers Directly

var taskStore = new InMemoryAncpTaskStore();
var cap       = new AncpNodeCapability(taskStore);
var node      = new PayrollEngineNode(mockPayrollService, mockTaxCalc);
node.InitializeAncp(cap, ancpClient: null);

var ctx = new AncpActionContext
{
    Action  = "get-payroll-status",
    Pattern = "request-reply",
    Payload = JsonSerializer.SerializeToElement(new { employeeId = 42 }),
    CallerIdentity = new AncpCallerIdentity { Mode = AncpAuthMode.ApiKey, Roles = ["invoke"] }
};

var result = await cap.DispatchAsync(ctx);

Assert.Equal(AncpDispatchResultKind.Response, result.Kind);

18 Error Codes

19 HTTP Status Code Reference

20 Changelog

21 Contributors

The following individuals contributed to the design, architecture, and implementation of the ANCP specification and BizFirst reference implementation.