A2A Remote Agent Server icon

A2A Remote Agent Server

Start A2A (Agent-to-Agent) Server to receive tasks from clients
Join our community

Overview

This node implements an A2A (Agent-to-Agent) Remote Agent Server that listens for incoming task requests from clients over HTTP. It acts as a bridge to receive, process, and manage tasks using n8n workflows. The node supports synchronous, asynchronous, or mixed processing modes, allowing flexible handling of tasks either by waiting for workflow results or accepting tasks immediately for later processing.

Common scenarios where this node is beneficial include:

  • Integrating external systems or agents that submit tasks to be processed by n8n workflows.
  • Orchestrating complex automation workflows triggered remotely.
  • Providing a standardized API endpoint for task submission, status querying, and capability discovery.
  • Supporting real-time updates and push notifications via technical capabilities like SSE or webhooks.

Practical examples:

  • An external application submits data transformation tasks to the agent, which processes them through configured workflows and returns results synchronously.
  • A monitoring system sends alert tasks asynchronously; the agent accepts them immediately and updates status later.
  • Multiple client agents query the capabilities and health of this agent before submitting tasks.

Properties

Name Meaning
Agent ID Unique identifier for this A2A agent instance. Used to distinguish this agent in communications and registry.
Port TCP port number on which the agent server listens for incoming A2A requests. Must be unique to avoid conflicts.
Processing Mode How incoming tasks are processed:
- Synchronous: Wait for workflow execution and return results immediately.
- Asynchronous: Accept tasks immediately and process later.
- Mixed: Support both based on client request.
Enable Workflow Integration Whether to forward received tasks to connected n8n workflow nodes for processing.
Authentication Mode Method to authenticate incoming requests:
- None: No authentication.
- Bearer Token: Require Bearer token in Authorization header.
- API Key: Require API key in Authorization header.
Auto-Register with Registry Automatically register this agent with an external A2A Registry server upon startup.
Registry URL URL of the A2A Registry Server to register with (used only if auto-register is enabled).
Technical Capabilities Protocol features supported by this agent, can select multiple:
- Streaming Support (SSE): Real-time updates via Server-Sent Events.
- Push Notifications: Webhook-based notifications.
- State Transition History: Detailed task state history.
Agent Skills JSON configuration defining the agent's functional skills and capabilities compliant with A2A spec. Each skill includes id, name, description, input/output modes, category, tags, examples, and enabled flag.

Output

The node outputs events related to the agent server lifecycle and task processing as JSON objects. Typical output fields include:

  • event_type: Type of event (e.g., "a2a_server_ready", "task_received", "a2a_task_status_requested").
  • agent_id: The configured agent identifier.
  • a2a_protocol_version: Protocol version string ("1.0").
  • Task-related fields such as task_id, session_id, status, processing_mode, workflow_result, completed_at, etc.
  • Workflow integration details when tasks are forwarded to workflows.
  • Status and error messages for task processing and server health.

If binary data were involved, it would be indicated, but this node primarily handles JSON/text data for tasks and statuses.

Dependencies

  • Requires an HTTP server environment (uses Express.js internally).
  • Optional connection to an external A2A Registry server for automatic registration.
  • May require valid API authentication tokens or keys depending on the selected authentication mode.
  • Relies on n8n workflow infrastructure to process tasks when workflow integration is enabled.
  • Uses environment or node parameters to configure ports and URLs.

Troubleshooting

  • Port Conflicts: If the configured port is already in use, the node will throw an error during activation. Use the provided validation script (validate-a2a-ports.js) to check port availability before saving.
  • Authentication Errors: Requests missing required authorization headers or with incorrect token formats will be rejected with 401 errors indicating the expected authentication method.
  • Task Processing Timeout: In synchronous mode, if workflow processing exceeds 30 seconds, a timeout error is returned suggesting switching to asynchronous mode for long-running workflows.
  • Invalid Requests: Malformed JSON-RPC requests or unsupported methods result in 400 errors with descriptive messages.
  • Registry Registration Failures: If auto-registration fails due to network or server issues, the node logs the failure but continues running.
  • Workflow Integration Disabled: Tasks will not be forwarded to workflows if integration is disabled, resulting in limited processing capabilities.

Links and References

Discussion