n8n-nodes-a2a

!Banner image

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:

$3

``bash


In your n8n directory

npm install n8n-nodes-a2a

Restart n8n

pm2 restart n8n
`

$3

`bash


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
`

$3

`bash


In your n8n directory

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

Restart n8n

pm2 restart n8n
`

$3

`dockerfile
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:

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

#### Send Standard Message

`javascript
{
"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

`javascript
{
"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

`javascript
{
"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

`javascript
{
"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

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

$3

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

#### Request Format
`json
{
"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
`json
{
"jsonrpc": "2.0",
"result": {
"status": {
"message": {
"parts": [
{
"type": "text",
"text": "Agent response here..."
}
]
}
}
},
"id": "call-789"
}
`

#### Error Response
`json
{
"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

$3

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

$3

`bash
npm run build
`

$3

`bash
npm run lint
npm run lintfix # Auto-fix issues
`

$3

`bash
npm run dev # Watch mode for development
`

$3

`
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

$3

- 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

$3

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

$3

- 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

$3

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

$3

- 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

$3

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

$3

- 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.

$3

- 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

$3

`javascript
// 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.

$3

Execute o servidor de exemplo:
`bash
python examples/simple_a2a_server.py
`

Teste com o cliente:
`bash
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

$3

`python


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

`bash


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

$3

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

$3

`javascript
// 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.

$3

- 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!