Overview
This node implements an A2A (Agent-to-Agent) Agent Registry server that facilitates the discovery, registration, and management of agents within a network. It listens on a specified port and exposes RESTful endpoints to allow agents to register themselves, send heartbeats, be discovered by others, and provide status information.
Common scenarios where this node is beneficial include:
- Managing a fleet of distributed agents or services that need to discover each other dynamically.
- Centralizing agent metadata and capabilities for orchestration or monitoring purposes.
- Enabling secure communication between agents through configurable authentication modes.
Practical examples:
- A workflow that automatically registers new microservices as they come online and tracks their health.
- Discovering agents with specific capabilities to delegate tasks dynamically.
- Monitoring active agents and their statuses in real-time for operational insights.
Properties
| Name | Meaning |
|---|---|
| Registry Name | The name of the agent registry instance. Used for identification and display purposes. Default is "N8N A2A Registry". |
| Port | The TCP port number on which the registry server listens for incoming HTTP requests from agents. Must be unique to avoid conflicts. Default is 8080. |
| Enable Agent Discovery | Boolean flag to enable or disable the ability for clients to discover registered agents via the registry. When disabled, discovery endpoints return a forbidden error. |
| Authentication Mode | The method of authentication required for registry requests. Options are: None (no authentication), Bearer Token (requires Bearer token in Authorization header), or API Key (requires API key in Authorization header). |
| Registry Configuration | JSON object defining metadata about the registry such as description, version, supported protocols, and features. This configures the registry's advertised capabilities and info returned by info endpoints. |
Output
The node outputs JSON objects representing events and data related to the registry's operation. These include:
- Agent registration events: Details about newly registered agents including their ID, capabilities, and timestamps.
- Agent discovery results: Lists of agents matching query parameters like capability and status.
- Heartbeat acknowledgments: Confirmation that an agent's heartbeat was received and its status updated.
- Agent unregistration events: Information about agents removed from the registry.
- Registry status updates: General info about the registry readiness, total agents, enabled features, and configuration.
The output JSON structure varies depending on the event but generally includes fields such as event_type, agent_id, agent_data, registry_name, total_agents, and timestamps.
The node does not output binary data.
Dependencies
- Requires an environment capable of running Node.js and n8n workflows.
- Uses the Express framework internally to create the HTTP server and handle REST API routes.
- Depends on utility functions for port validation, URL detection, and server lifecycle management.
- No external API keys or credentials are embedded; however, authentication modes require clients to supply appropriate tokens or keys in request headers.
Troubleshooting
- Port conflicts: If the configured port is already in use, the node will throw an error during activation. Use the provided script (
validate-a2a-ports.js) to check for port conflicts before saving the workflow. - Invalid JSON in Registry Configuration: Malformed JSON in the registry configuration property causes an error. Ensure the JSON is valid.
- Authentication errors: Requests missing required authorization headers or with incorrect token formats will receive 401 Unauthorized responses. Verify that clients send the correct authentication tokens according to the selected mode.
- Agent not found errors: Requests targeting non-existent agents return 404 errors. Confirm agent IDs are correct.
- Agent discovery disabled: If discovery is disabled, discovery endpoint calls return 403 Forbidden errors.
- Server errors: Unexpected server errors emit descriptive messages. Check logs for details.
Links and References
- Express.js Documentation
- n8n Custom Nodes Guide
- Agent-to-Agent Communication Concepts (replace with actual relevant link if available)