IBM WatsonX Orchestrate Agent Node para n8n

Nó personalizado do n8n para integração com IBM watsonx Orchestrate.

📋 Características

• ✅ Sem dependências de banco de dados
• ✅ Configuração simplificada
• ✅ Suporte automático a templates com variáveis
• ✅ Timeout configurável
• ✅ Compatível com watsonx Orchestrate API

🔧 Instalação

1. Copie os arquivos para o diretório de nodes customizados do n8n
2. Reinicie o n8n

📝 Configuração

Credenciais (IBM Watson API)

Vá em Credentials → New → IBM Watson AI API e configure:

• API Key: Sua chave de API do IBM Cloud

Parâmetros do Nó

Campos Obrigatórios

1. URL da API

   • URL base da API do WatsonX Orchestrate
   • Padrão: https://api.br-sao.watson-orchestrate.cloud.ibm.com
   • Varia de acordo com a região da sua instância

2. Instance

   • ID da instância do WatsonX Orchestrate
   • Formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. Agent ID

   • ID do agente watsonx Orchestrate
   • Formato: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

4. Instrução para IA

   • Mensagem ou pergunta que será enviada ao agente
   • Suporta automaticamente variáveis do input anterior usando {{nome_do_campo}}

Opções Adicionais

• Timeout: Tempo máximo de espera (padrão: 30 segundos)

💡 Exemplos de Uso

Exemplo 1: Mensagem Simples

URL: https://api.br-sao.watson-orchestrate.cloud.ibm.com
Instance: abc123-def456-ghi789
Agent ID: xyz987-uvw654-rst321
Instrução: "Qual é o status dos chamados de hoje?"

Exemplo 2: Com Variáveis (Template automático)

Configure a instrução com variáveis:

Instrução: "Consulte o chamado número {{ticket_number}} do cliente {{customer_name}}"

Se o input anterior tiver:

{
  "ticket_number": "INC0012345",
  "customer_name": "João Silva"
}

A mensagem enviada será automaticamente:

"Consulte o chamado número INC0012345 do cliente João Silva"

Nota: O processamento de variáveis {{campo}} é sempre automático - não há necessidade de ativar nenhuma opção.

🔗 Estrutura da Requisição

A requisição é formada da seguinte maneira:

POST {URL}/instances/{Instance}/v1/orchestrate/{Agent ID}/chat/completions

Exemplo:

POST https://api.br-sao.watson-orchestrate.cloud.ibm.com/instances/abc123-def/v1/orchestrate/xyz789-uvw/chat/completions

Headers:

• Authorization: Bearer {token}
• IAM-API_KEY: {sua-api-key}
• Content-Type: application/json

Body:

{
  "model": "{Agent ID}",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "sua mensagem aqui"
    }
  ],
  "additional_properties": {}
}

📤 Output

O nó retorna um objeto JSON com:

{
  "ai_response": "Resposta do agente Watson",
  "input_recebido": { /* dados do input */ },
  "instrucao_enviada": "mensagem processada",
  "watson_response_completa": { /* resposta completa da API */ },
  "success": true,
  "timestamp": "2024-03-15T10:30:00.000Z"
}

Em caso de erro:

{
  "erro": true,
  "mensagem": "Descrição do erro",
  "detalhes": "Detalhes técnicos",
  "success": false,
  "timestamp": "2024-03-15T10:30:00.000Z"
}

🔗 URLs da API por Região

• São Paulo: https://api.br-sao.watson-orchestrate.cloud.ibm.com
• Dallas: https://api.us-south.watson-orchestrate.cloud.ibm.com
• Washington DC: https://api.us-east.watson-orchestrate.cloud.ibm.com
• Frankfurt: https://api.eu-de.watson-orchestrate.cloud.ibm.com
• Londres: https://api.eu-gb.watson-orchestrate.cloud.ibm.com
• Sydney: https://api.au-syd.watson-orchestrate.cloud.ibm.com
• Tóquio: https://api.jp-tok.watson-orchestrate.cloud.ibm.com

🛠️ Troubleshooting

Erro de Autenticação

• Verifique se a API Key está correta
• Certifique-se de que a chave tem permissões adequadas

Erro 404

• Confirme se Instance e Agent ID estão corretos
• Verifique se a URL da API corresponde à região da sua instância
• Certifique-se de que a URL segue o formato: {URL}/instances/{Instance}/v1/orchestrate/{AgentID}/chat/completions

Timeout

• Aumente o valor do timeout nas opções avançadas
• Verifique a conectividade com a API da IBM

Variáveis não substituídas

• Verifique se os nomes dos campos no template correspondem exatamente aos campos do input
• Use a sintaxe {{nome_do_campo}} (com chaves duplas)
• Os nomes são case-sensitive

📄 Versão

2.0.0 - Versão simplificada sem banco de dados, com suporte automático a templates

📞 Suporte

Para problemas relacionados ao IBM watsonx Orchestrate, consulte:

• Documentação IBM Watson
• watsonx Orchestrate