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