n8n-nodes-garza-a2a

A production-grade n8n community node package that implements
Google's Agent2Agent (A2A) protocol v0.3. It lets
an n8n instance act as both:

• an A2A client — call remote A2A agents from a workflow, and
• an A2A server — expose any n8n workflow as a real A2A agent with a valid
  Agent Card.

It is built on the official @a2a-js/sdk
v0.3.13 and targets A2A protocol v0.3, using the current Agent Card path
/.well-known/agent-card.json (with a legacy /.well-known/agent.json alias).

This package is a GARZA OS project.

---

Contents

• Installation
• Nodes
  • A2A Client
  • A2A Server Trigger
• Credential: A2A API
• Usage examples
• A2A v0.3 Agent Card path
• Design notes
• Development
• License

---

Installation

Community Nodes (recommended)

1. In n8n, go to Settings → Community Nodes.
2. Click Install.
3. Enter the npm package name: n8n-nodes-garza-a2a
4. Agree to the risks and click Install.

After installation the A2A Client and A2A Server Trigger nodes appear in
the node panel, and the A2A API credential becomes available.

Requires n8n running on Node.js 20.15+ (the A2A SDK requires Node 18+).

Manual / self-hosted

# in your n8n custom-nodes directory (e.g. ~/.n8n/custom)
npm install n8n-nodes-garza-a2a

Set N8N_CUSTOM_EXTENSIONS to the directory if needed, then restart n8n.

---

Nodes

A2A Client (action node)

Resource Agent, with operations:

Operation	Description
Discover Agent Card	Resolve /.well-known/agent-card.json from a base URL and output the Agent Card.
Send Message	Send a text message; returns the resulting Task or Message. Supports a Blocking toggle.
Send Message (Stream)	Send a message over SSE; collects all streamed events plus the final result and aggregated text.
Get Task	Retrieve a task by ID (tasks/get).
Cancel Task	Request cancellation of a task by ID (tasks/cancel).

Parameters: Agent Base URL (falls back to the credential's Base URL),
Message Text, optional Context ID / Task ID, and Blocking.

Because n8n nodes cannot stream incrementally to the UI, the streaming operation
collects every SSE event into an ordered events[] array and also returns the
final event and an aggregated text field.

A2A Server Trigger (node)

A trigger node that turns the workflow into an A2A agent. It exposes an n8n
webhook that speaks A2A:

• GET <webhook>/.well-known/agent-card.json → the v0.3 Agent Card
• GET <webhook>/.well-known/agent.json → legacy alias (same card)
• GET <webhook> → also returns the Agent Card
• POST <webhook> → JSON-RPC 2.0 (message/send, message/stream)

Configurable: Webhook Path, Agent Name, Description, Version,
Public Base URL (advertised as the card's url), Enable Streaming,
Enable Push Notifications, and a repeatable Skills collection
(id, name, description, comma-separated tags and examples).

On an incoming message/send, the node:

1. responds to the calling agent with a spec-compliant completed Task
   (the inbound message becomes the task history; the text becomes a
   completed-status message and a text artifact), and
2. emits the inbound message into the workflow under json.a2a so downstream
   nodes can process it (a2a.text, a2a.message, a2a.taskId,
   a2a.contextId, a2a.task).

---

Credential: A2A API

One credential (A2A API) is shared by both nodes.

Field	Applies to	Notes
Base URL	client	Optional default base URL for the remote agent.
Authentication Type	client	none, bearer, apiKey, or oauth2ClientCredentials.
Bearer Token	bearer	Sent as Authorization: Bearer <token>.
API Key Header Name	apiKey	Defaults to X-API-Key.
API Key	apiKey	Value sent in the configured header.
Token URL / Client ID / Client Secret / Scope	oauth2ClientCredentials	Client-credentials grant; tokens are fetched and cached in-memory with auto-refresh on 401/403.

Auth is wired into the SDK via a custom authenticating fetch
(createAuthenticatingFetchWithRetry), so credentials are injected on every
request and refreshed automatically.

---

Usage examples

n8n as a client calling a remote agent

1. Add an A2A Client node.
2. Create an A2A API credential (e.g. Bearer token) and select it.
3. Set Operation = Send Message, Agent Base URL =
   https://remote-agent.example.com, and Message Text = Hello agent!.
4. Execute — the node returns the resulting Task/Message.

A ready-to-import workflow is provided in
examples/client-send-message.workflow.json.

n8n as a server exposed to another agent

1. Add an A2A Server Trigger node as the workflow's trigger.
2. Set the Agent Name, Description, Version, and add one or more
   Skills.
3. Activate the workflow. The agent card is now served at
   https://<your-n8n>/webhook/<path>/.well-known/agent-card.json.
4. Point any A2A client (including the A2A Client node above) at
   https://<your-n8n>/webhook/<path> to discover and message your agent.

---

A2A v0.3 Agent Card path

A2A v0.3 moved the well-known Agent Card path from /.well-known/agent.json
to /.well-known/agent-card.json. This package uses the v0.3 path
everywhere (client discovery and server publishing) and the server additionally
answers the legacy /.well-known/agent.json path with the same card for
backwards compatibility with older clients.

---

Design notes

The official @a2a-js/sdk server runtime (A2AExpressApp,
DefaultRequestHandler) assumes a long-lived Express server. n8n trigger nodes
do not run a standalone server — they expose request-scoped webhooks. So
rather than booting Express, the A2A Server Trigger implements the A2A
transport directly on top of n8n's webhook() lifecycle (GET = Agent Card,
POST = JSON-RPC 2.0), which keeps protocol behavior correct while fitting n8n's
execution model. The client node uses the SDK's non-deprecated ClientFactory
over the JSON-RPC transport so results are returned unwrapped and typed SDK
errors are surfaced cleanly as NodeOperationErrors.

---

Development

npm install      # install dependencies
npm run build    # compile TypeScript to dist/ and copy icons
npm run lint     # eslint-plugin-n8n-nodes-base (what n8n verification checks)
npm run format   # prettier

---

License

MIT © Jaden Garza / GARZA OS