n8n-nodes-a2a

This is an n8n community node that provides A2A (Account to Account) operations for transfers and account management.

A2A enables secure account-to-account transfers and comprehensive account management through a unified API interface.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage Examples
Resources

🚀 Installation

The A2A node can be installed using multiple methods:

Option 1: Via npm (Recommended)

# In your n8n directory
npm install n8n-nodes-a2a

# Restart n8n
pm2 restart n8n

Option 2: Automated Script

# Install from npm (default)
curl -fsSL https://raw.githubusercontent.com/your-username/n8n-nodes-a2a/main/install-a2a-node.sh | bash

# Install from GitHub
curl -fsSL https://raw.githubusercontent.com/your-username/n8n-nodes-a2a/main/install-a2a-node.sh | bash -s -- --github

Option 3: Manual Installation from GitHub

# In your n8n directory
npm install https://github.com/your-username/n8n-nodes-a2a.git

# Restart n8n
pm2 restart n8n

Option 4: Docker

FROM n8nio/n8n:latest

USER root
RUN cd /usr/local/lib/node_modules/n8n && \
    npm install n8n-nodes-a2a
USER node

For detailed installation instructions including troubleshooting, see:

• Quick Guide: INSTALL_SELFHOST.md
• Detailed Guide: docs/N8N_SELFHOST_INSTALL.md

Operations

This node provides comprehensive A2A functionality through three main resources:

Transfer Resource

• Create Transfer: Create a new account-to-account transfer
• Get Transfer: Get details of a specific transfer by ID
• List Transfers: Get a list of transfers with filtering options
• Cancel Transfer: Cancel a pending transfer

Account Resource

• Get Account: Get details of a specific account
• List Accounts: Get a list of accounts with filtering options
• Get Balance: Get account balance information
• Get Transactions: Get account transaction history with date filtering

Agent Resource (Google Agent2Agent Protocol)

• Send Message: Send a message to an agent and receive complete response (tasks/send)
• Send Message with Streaming: Send a message with real-time streaming response (tasks/sendSubscribe)
• Get Agent Card: Retrieve agent capabilities from .well-known/agent-card endpoint

Credentials

You need to authenticate with the A2A API using the following credentials:

1. API Key: Your A2A API key
2. API Secret: Your A2A API secret
3. Environment: Choose between Production or Sandbox
4. Base URL: Automatically set based on environment selection

Setting up credentials

1. Sign up for an A2A account and obtain your API credentials
2. In n8n, create new credentials using the "A2A API" credential type
3. Enter your API Key and Secret
4. Select the appropriate environment (Sandbox for testing, Production for live operations)
5. Test the credentials to ensure they work correctly

Usage Examples

Creating a Transfer

{
  "resource": "transfer",
  "operation": "create",
  "amount": 100.50,
  "currency": "USD",
  "fromAccountId": "acc_123456789",
  "toAccountId": "acc_987654321",
  "reference": "Service Payment",
  "description": "Monthly service payment"
}

Checking Account Balance

{
  "resource": "account",
  "operation": "getBalance",
  "accountId": "acc_123456789"
}

Listing Recent Transfers

{
  "resource": "transfer",
  "operation": "getMany",
  "limit": 50,
  "status": "completed"
}

Getting Transaction History

{
  "resource": "account",
  "operation": "getTransactions",
  "accountId": "acc_123456789",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "transactionLimit": 100
}

Agent2Agent Protocol Examples

Send Standard Message

{
  "resource": "agent",
  "operation": "send",
  "agentUrl": "https://agent-api.example.com",
  "message": "Hello! Can you help me with my query?",
  "sessionId": "session-123",
  "taskId": "task-456",
  "acceptedOutputModes": ["text", "image"],
  "additionalOptions": {
    "apiKey": "your-api-key",
    "responseFormat": "message",
    "role": "user",
    "timeout": 30000
  }
}

Send Message with File Upload

{
  "resource": "agent",
  "operation": "send",
  "agentUrl": "https://agent-api.example.com",
  "message": "Please analyze this document for me",
  "includeFiles": true,
  "files": {
    "file": [{
      "inputFieldName": "data",
      "fileName": "document.pdf", 
      "mimeType": "application/pdf"
    }]
  },
  "acceptedOutputModes": ["text", "code"],
  "additionalOptions": {
    "apiKey": "your-api-key",
    "responseFormat": "full",
    "maxRetries": 3,
    "retryDelay": 2000
  }
}

Send Message with Streaming

{
  "resource": "agent",
  "operation": "sendSubscribe",
  "agentUrl": "https://agent-api.example.com",
  "message": "Please provide a detailed analysis...",
  "sessionId": "session-123",
  "taskId": "task-789",
  "acceptedOutputModes": ["text", "image", "code"],
  "additionalOptions": {
    "apiKey": "your-api-key",
    "role": "user",
    "timeout": 60000,
    "streamProcessing": "final",
    "responseFormat": "auto",
    "headers": {
      "parameter": [
        {
          "name": "X-Custom-Header",
          "value": "custom-value"
        }
      ]
    }
  }
}

Custom JSON-RPC Request

{
  "resource": "agent",
  "operation": "custom",
  "agentUrl": "https://agent-api.example.com",
  "customMethod": "tasks/analyze",
  "customParams": {
    "message": {
      "role": "user",
      "parts": [{
        "type": "text",
        "text": "Custom analysis request"
      }]
    },
    "sessionId": "custom-session",
    "analysisType": "deep",
    "outputFormat": "json"
  },
  "additionalOptions": {
    "apiKey": "your-api-key",
    "timeout": 45000,
    "validateSSL": true
  }
}

Get Agent Capabilities

{
  "resource": "agent",
  "operation": "getAgentCard",
  "agentUrl": "https://agent-api.example.com"
}

JSON-RPC 2.0 Protocol

The Agent resource implements the Google Agent2Agent protocol using JSON-RPC 2.0:

Request Format

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Your message here"
        }
      ]
    },
    "sessionId": "session-123",
    "id": "task-456"
  },
  "id": "call-789"
}

Success Response

{
  "jsonrpc": "2.0",
  "result": {
    "status": {
      "message": {
        "parts": [
          {
            "type": "text",
            "text": "Agent response here..."
          }
        ]
      }
    }
  },
  "id": "call-789"
}

Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Error message"
  },
  "id": "call-789"
}

Supported Currencies

• USD (US Dollar)
• EUR (Euro)
• GBP (British Pound)
• BRL (Brazilian Real)

Error Handling

The node includes comprehensive error handling for common scenarios:

• 401 Unauthorized: Invalid API credentials
• 404 Not Found: Account or transfer not found
• 400 Bad Request: Invalid parameters or insufficient funds
• 429 Rate Limited: Too many requests

Compatibility

• Minimum n8n version: 1.0.0
• Node.js version: 20.15+
• Tested with n8n versions: 1.0.0+

Development

Prerequisites

• Node.js 20.15 or higher
• npm or yarn
• n8n installed globally

Building

npm run build

Linting

npm run lint
npm run lintfix  # Auto-fix issues

Development Mode

npm run dev  # Watch mode for development

Project Structure

n8n-nodes-a2a/
├── credentials/
│   └── A2aApi.credentials.ts     # API credentials definition
├── nodes/
│   └── A2a/
│       ├── A2a.node.ts          # Main node implementation
│       ├── TransferDescription.ts # Transfer operations
│       ├── AccountDescription.ts  # Account operations
│       ├── a2a.svg              # Node icon
│       └── A2a.node.json        # Node metadata
├── examples/
│   └── A2A_Example_Workflow.json # Example workflow
└── docs/
    └── INSTALLATION.md           # Detailed installation guide

Example Workflow

Import the example workflow from examples/A2A_Example_Workflow.json to see:

1. How to create a transfer
2. How to check transfer status
3. How to verify account balance
4. Error handling best practices

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run linting and build
6. Submit a pull request

Resources

• n8n community nodes documentation
• A2A API Documentation
• A2A Authentication Guide
• Transfer API Reference
• Account API Reference
• Agent2Agent Protocol:
  • Google A2A Repository
  • A2A Testing Lab
  • Agent2Agent Protocol Documentation
  • JSON-RPC 2.0 Specification

Support

For support and questions:

1. Documentation: Check the official A2A API docs
2. Agent2Agent Protocol: See Agent2Agent Documentation
3. Issues: Report bugs on GitHub Issues
4. Community: Join the n8n community forum

License

MIT

🚀 Advanced Features

File Upload Support

• Automatic Base64 encoding of binary data
• Multiple file types with custom MIME type detection
• File name customization and metadata preservation
• Integration with n8n binary data system

Advanced Authentication

• API Key support with x-api-key header
• Custom headers for specialized authentication
• SSL validation control for development/testing

Response Processing

• Multiple format options: Auto, Full Response, Message Only, Status Only
• Streaming event processing: Collect All, Final Only, Individual Events
• Metadata inclusion for debugging and monitoring

Retry & Error Handling

• Configurable retry logic (0-10 attempts)
• Custom retry delays (100-10000ms)
• Automatic error categorization with JSON-RPC error codes

Output Modes

• Text: Standard text responses
• Image: Image generation and analysis
• Audio: Audio processing capabilities
• Video: Video analysis and generation
• Code: Code generation and analysis

See Advanced Features Documentation for complete details.

📋 Funcionalidades

Operações A2A Financeiras

• Transfer: Transferências entre contas
• Account: Consulta de informações de conta

Protocolo Agent2Agent

• Agent Operations: Comunicação completa com agentes IA via protocolo A2A
• Custom Requests: Requisições JSON-RPC personalizadas
• File Upload: Suporte a upload de arquivos com encoding base64
• Streaming: Processamento de respostas em tempo real
• Authentication: Autenticação via x-api-key

🤖 Agent2Agent Protocol

Este nó suporta o protocolo Agent2Agent (A2A) do Google, permitindo comunicação padronizada entre agentes de IA.

Recursos Avançados

• Custom JSON-RPC: Construa requisições personalizadas
• File Upload: Anexe arquivos com detecção automática de MIME type
• API Key Auth: Autenticação segura via header x-api-key
• Multi-format Output: Suporte a texto, imagem, áudio, vídeo, código
• Retry Logic: Sistema robusto de tentativas
• Streaming Support: Processar respostas em tempo real

Exemplo de Uso

// Configuração básica
{
  "operation": "send",
  "agentUrl": "https://agent.example.com",
  "message": "Analyze this data and provide insights",
  "responseFormat": "auto"
}

// Com upload de arquivo
{
  "operation": "send", 
  "agentUrl": "https://agent.example.com",
  "message": "Process this image",
  "includeFiles": true,
  "files": "image.png",
  "responseFormat": "full"
}

🔧 Criando Seu Próprio Servidor A2A

Você pode criar seus próprios servidores Agent2Agent! Veja o guia completo em docs/AGENT2AGENT_SERVER.md.

Exemplo Rápido

Execute o servidor de exemplo:

python examples/simple_a2a_server.py

Teste com o cliente:

python examples/test_a2a_client.py

O servidor oferece:

• 🔄 Echo Skill: Repete mensagens
• 🧮 Calculator: Operações matemáticas básicas
• 📋 Agent Card: Descoberta automática de capacidades
• ✅ Health Check: Monitoramento de status

Estrutura Básica

# Agent Card - Descreve capacidades
AGENT_CARD = {
    "name": "Meu Agente",
    "description": "Descrição das funcionalidades",
    "skills": [
        {
            "id": "minha_skill",
            "name": "Minha Habilidade",
            "description": "O que esta skill faz"
        }
    ]
}

# Endpoint obrigatório - Agent Card
@app.route("/.well-known/agent.json")
def get_agent_card():
    return jsonify(AGENT_CARD)

# Endpoint obrigatório - Processar tarefas
@app.route("/tasks/send", methods=["POST"])
def handle_task():
    task = request.get_json()
    # Processar tarefa aqui
    return jsonify(response)

📚 Documentação

• 🔧 Instalação Completa
• 🏠 Instalação Self-hosted
• 🤖 Protocolo Agent2Agent
• ⚡ Recursos Avançados
• 🛠️ Criar Servidor A2A

🛠️ Desenvolvimento

# Clone e configure
git clone https://github.com/brunobs/n8n-node-a2a.git
cd n8n-node-a2a

# Instale dependências
npm install

# Build do projeto
npm run build

# Lint e format
npm run lint
npm run format

# Testes
npm test

📝 Exemplos

Operações A2A Básicas

// Transfer operation
{
  "resource": "transfer",
  "operation": "create",
  "amount": 100.50,
  "fromAccount": "12345",
  "toAccount": "67890"
}

Agent2Agent Avançado

// Enviar tarefa para agente
{
  "resource": "agent",
  "operation": "send", 
  "agentUrl": "https://my-agent.com",
  "message": "Analyze sales data",
  "acceptedOutputModes": ["text", "image"],
  "maxRetries": 3
}

// Upload de arquivo
{
  "resource": "agent",
  "operation": "send",
  "agentUrl": "https://my-agent.com", 
  "message": "Process this document",
  "includeFiles": true,
  "files": "document.pdf"
}

🔗 Links Úteis

• Especificação Agent2Agent
• Repositório Google A2A
• n8n Documentation
• Google Agent Development Kit

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch para sua feature
3. Faça commit das mudanças
4. Execute os testes
5. Abra um Pull Request

📄 Licença

MIT License - veja LICENSE.md para detalhes.

🏷️ Versão

v0.3.0 - Recursos avançados Agent2Agent com upload de arquivos, autenticação e streaming.

Changelog

• v0.3.0: Recursos avançados A2A, custom requests, file upload
• v0.2.0: Implementação completa do protocolo Agent2Agent
• v0.1.0: Operações básicas A2A financeiras

⭐ Se este projeto te ajudou, considere dar uma estrela no GitHub!