Conexões

Uma conexão é um servidor mais uma credencial, cadastrados uma vez, com nome próprio. As etapas apontam para ela pelo nome — nunca para um host e uma senha escritos dentro do fluxo.

É o que separa "este agente fala com o ERP" de "este agente carrega a senha do ERP".

Os cinco tipos

Tipo	Serve para	Usado por
http	uma API com endereço-base e autenticação	Consultar uma API
postgres	um banco relacional	Consultar banco de dados
smtp	um servidor de e-mail	Enviar e-mail
ssh	uma máquina registrada	Executar por SSH · SFTP
s3	armazenamento compatível com S3	Ler e gravar arquivos

Cada conexão vive num Agent Space e pertence à organização. O nome é único por tipo dentro do espaço: você pode ter financeiro em postgres e financeiro em smtp, e as duas são coisas distintas.

A credencial entra uma vez e não volta

você digita  →  cofre de secrets  →  a etapa recebe uma REFERÊNCIA

O que fica guardado na conexão são os campos não-secretos: host, porta, usuário, endereço-base. O segredo vai para o cofre e a conexão guarda só um ponteiro.

Consequências que você vai notar:

• ao editar uma conexão, o campo de senha aparece vazio. Não é defeito: o valor não é recuperável para exibição. Deixe em branco e ele permanece o que era; preencha e ele é substituído;
• o que é gravado na definição do agente é a referência, nunca o valor. Uma versão publicada não carrega credencial;
• a conversa com o Imaginne também não a alcança: lá existe o nome da conexão. Se alguém pedir a senha na conversa, a resposta certa é abrir a tela — e é o que ele faz.

Testar conecta de verdade

O botão Testar não confere o formulário: ele abre a conexão real.

Tipo	O que o teste faz
smtp	STARTTLS e autenticação
postgres	um SELECT version()
s3	uma listagem
ssh	executa um comando trivial
http	uma sondagem no endereço-base

Um teste que passa prova que a credencial serve agora. É a diferença entre descobrir o erro aqui e descobri-lo na primeira execução agendada, de madrugada.

Na etapa

Quando a etapa tem uma conexão escolhida, os campos que a conexão já responde somem do painel — host, porta, usuário, endereço-base. Não ficam preenchidos e cinzentos: somem. Dois lugares para dizer a mesma coisa é como as duas versões divergem.

O seletor de conexões aparece dentro da própria etapa. Não é preciso sair para a página de conexões para escolher.

O que a publicação recusa

A validação roda antes de existir versão, e recusa:

• etapa apontando para uma conexão que não existe no espaço;
• conexão do tipo errado para aquela etapa — um smtp numa etapa de banco;
• credencial escrita dentro da etapa, quando o campo aceitaria uma conexão.

Recusar na publicação é de propósito: um fluxo que só falha na primeira execução já virou versão imutável e já está no ar.

SSH: a chave do servidor é fixada

Uma conexão ssh guarda a host key da máquina registrada, e o executor exige exatamente aquela chave, do mesmo tipo.

Se o servidor apresentar outra chave — porque foi reinstalado, ou porque não é ele —, a conexão é recusada em vez de seguir. É o comportamento que você quer: uma máquina trocada no meio do caminho não recebe a sua credencial.

Registre a chave do tipo certo

O tipo da chave registrada (ed25519, ecdsa, rsa) é fixado junto. Um servidor que apresenta uma chave legítima de outro tipo é recusado, porque nada distingue esse caso de uma troca indevida.

Quem pode o quê

Conexões são governadas pelo Agent Space, como o resto:

Perfil	Ver	Criar e editar	Usar numa etapa
creator	✅	✅	✅
publisher	✅	✅	✅
admin	✅	✅	✅

O que separa os ambientes não é o perfil: um secret exclusivo de produção é bloqueado em desenvolvimento. Ver Ambientes.

Próximos passos

• Consultar uma API
• Componentes de sistema
• Recursos liberados