LabAcacia.A2aIngress 1.0.0-alpha.16

English | 中文版

LabAcacia.A2aIngress

An ASP.NET Core library that exposes a single NPS NWP Action / Complex Node as a Google Agent-to-Agent (A2A) server. A2A-speaking peer agents can discover the node via /.well-known/agent.json and invoke NWP actions through standard JSON-RPC 2.0 without knowing anything about NPS.

• Protocol: A2A v0.2 — JSON-RPC 2.0 over HTTP POST.
• Target: .NET 10, ASP.NET Core.
• NWP spec: spec/NPS-2-NWP.md v0.14 (Action Node §7, async lifecycle §7.2, system.task.status / system.task.cancel §7.3).

What it does

Skill selection: tasks/send picks the upstream action_id from (in order) —

1. params.metadata.skillId (+ optional params.metadata.params).
2. message.metadata.skillId (+ optional message.metadata.params).
3. The first data part in message.parts, keyed by skillId / skill_id / action_id.

Install

dotnet add package LabAcacia.A2aIngress

Quick start

using LabAcacia.NPS.A2aIngress;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRouting();
builder.Services.AddA2aIngress(o =>
{
    o.AgentName        = "OrdersAgent";
    o.AgentDescription = "Create and cancel customer orders.";
    o.AgentVersion     = "1.0.0";
    o.PublicUrl        = new Uri("https://bridge.example.com/a2a");
    o.Upstream         = new A2aUpstream
    {
        BaseUrl    = new Uri("https://action.internal/orders"),
        AgentNid   = "urn:nps:nid:agent:a2a-ingress",
        AuthHeader = "Bearer <service-token>",
    };
});

var app = builder.Build();
app.UseRouting();
app.UseEndpoints(e => e.MapA2aIngress());   // GET /.well-known/agent.json, POST /a2a
app.Run();

Point any A2A-compatible client at https://bridge.example.com/.

Configuration

A2aIngressOptions:

A2aUpstream:

Error mapping

Standard JSON-RPC (-32700 … -32603) plus A2A application errors:

Bridge failures appear as the returned Task.status.state = "failed" with an agent message carrying the upstream HTTP body, rather than as JSON-RPC errors — this lets A2A clients treat them uniformly with other task failures.

JSON-RPC notifications (requests without id) receive HTTP 204 No Content.

Task-tracking note

The bridge holds an in-process map of {a2a_task_id → upstream_task_id} so that tasks/get and tasks/cancel can rewrite the request onto the correct upstream task. Restarting the ingress forgets async tasks in flight. For production multi-replica deployments, replace the in-memory dictionary with a shared store (out of scope for v0.1).

Testing

dotnet test tests/LabAcacia.A2aIngress.Tests/LabAcacia.A2aIngress.Tests.csproj

Tests run against a stub HttpMessageHandler — no network required.

Further reading

• A2A Ingress deep dive — 1:1 AgentCard mapping, skill lookup, task state translation, in-memory binding map, replica notes
• Compat ingresses overview — when to pick MCP / A2A / gRPC

License

Apache 2.0. See LICENSE and NOTICE at the repo root.