A conversa no Canvas

O cartão de Conversa é onde a conversa com um assistente vive dentro do quadro. Ele é uma das superfícies de conversa do produto — e não é a mesma coisa que uma conversa da tela Conversa.

Um lugar próprio

A decisão de produto é que as telas sejam independentes: uma conversa no Canvas não é a conversa da tela Conversa vista de outro ângulo. As duas superfícies mantêm conversas separadas, cada uma com a sua própria sessão.

Cuidado com a expectativa. Não conte com “a conversa da tela Conversa aparece no Canvas” — e não conte com o contrário — como comportamento garantido. Trate as duas como lugares distintos.

O que isso significa na prática: abrir um cartão de conversa no quadro cria uma conversa ali. Ela não é a mesma que você tinha aberto na outra tela.

O cartão de conversa principal é o maestro

O cartão de conversa principal do projeto é o orquestrador: quando ele cria agentes filhos, cada filho aparece como um cartão ligado a ele por uma linha.

A sessão

• A sessão vive no processo principal do app. Mudar o layout, minimizar o cartão ou trocar de tela não interrompe a conversa.
• A sessão não aparece na lista de terminais. Uma conversa roda pelo SDK, com endereço próprio — procurá-la entre os terminais não acha nada. Isso é esperado, não é defeito.
• Uma conversa ociosa pode ser recolhida e recriada. Depois de um tempo sem uso, a sessão ociosa é encerrada para liberar recursos e recriada no próximo envio. Por isso uma conversa parada não custa um processo para sempre.
• O rascunho é preservado. O texto que você escreveu e ainda não enviou é guardado por conversa: ele sobrevive a trocar de tela, minimizar, recarregar a janela e reiniciar o app. Se a conversa terminar, o cartão mostra o que você tinha escrito, com as opções Copiar e Continuar em nova conversa.
• Fechar o cartão encerra a conversa e o rascunho daquela conversa é descartado junto.

O assistente da conversa

O assistente é escolhido na criação do cartão, e o modelo também: --model é aceito no cartão de conversa e só nele.

O caminho de conversa do Elyra é o do SDK, não o de digitar num terminal. Onde o SDK não puder dirigir o assistente, a tela diz que a conversa está indisponível ali — ela nunca cai para uma interface de terminal por conta própria.

Em worktree remoto (SSH), o caminho do SDK atravessa a conexão. Os demais assistentes seguem pelo caminho de terminal e não são locais por construção nesse cenário.

A escolha do assistente muda o que existe depois. Nem toda combinação de assistente e host oferece o mesmo conjunto de recursos na conversa. O que a tela mostra é condicionado ao que aquele adaptador oferece — não há paridade universal entre provedores.

Dirigir a conversa pela linha de comando

Um cartão de conversa tem um endereço estável, derivado da aba da conversa, no formato chat_<12 hex>. Ele é o mesmo depois de recarregar a janela, reiniciar o app e mover o cartão, e nunca colide com o endereço de um terminal.

elyra chat list [--workspace <selector>] [--json]
elyra chat send --chat <handle|tabId|nodeId|título> (--text <text> | --text-file <path|->) [--json]
elyra chat read --chat <handle|tabId|nodeId|título> [--limit <n>] [--json]

A lista traz os cartões de conversa do Canvas daquele workspace, com handle, id do cartão, assistente, título e indicador de trabalho. Ela não é a tela Conversa: as conversas daquela tela não aparecem aqui.

O envio aceita handle, id da aba, id do cartão ou o título exato. Um título repetido não identifica um destino: o runtime pede para você listar e desambiguar. Prefira o handle.

O que a resposta do envio significa

A resposta é {ok: true, handle, queued}.

queued: true significa que o turno já estava em andamento e a mensagem foi enfileirada — não que o assistente respondeu. O envio confirmado é o envio, não a resposta. Para ver a resposta, leia a conversa.

O que a leitura traz

A leitura é uma projeção simplificada: cada mensagem vem como {role, text, at}. Blocos que não são texto — o raciocínio do assistente e as chamadas de ferramenta — não aparecem nessa saída. A resposta traz truncated: true quando mensagens mais antigas foram descartadas.

Limites que valem saber agora

• A sessão precisa estar viva para receber mensagem. Um cartão cuja view ainda não montou não tem sessão no processo principal, e o envio é recusado com uma mensagem dizendo exatamente isso. Na prática: abra o Canvas para que o cartão monte e repita o envio. O envio não cria a sessão sozinho.
• Por causa disso, um filho de orquestração deve ser cartão de terminal, não cartão de conversa. Um terminal nasce sem depender da view montada e recebe a tarefa pelo endereço dele. O cartão de conversa serve para a conversa que você acompanha.
• A listagem pode mostrar cartões que o envio não alcança. O caminho de envio e leitura procura a sessão gerenciada no processo principal: ela existe para os cartões que rodam pelo SDK. Um cartão de outro assistente pode aparecer na lista sem ser alcançável pelo envio.
• A conversa não aparece na lista de terminais. Isso é consequência de rodar pelo SDK, não um cartão ausente.
• Título repetido não é endereço. Use o handle ou o id do cartão em qualquer automação.

Recuperação

Situação	O que fazer
O envio recusa dizendo que a sessão não existe	Abra o Canvas para montar o cartão e repita o envio.
O nome do cartão é ambíguo	Liste os cartões com --json e use o handle.
A leitura não traz o raciocínio nem as ferramentas	Esperado: a leitura pela linha de comando projeta só texto. Use o cartão na tela para a conversa completa.
A conversa terminou e você tinha texto escrito	O cartão mostra o rascunho; use Copiar antes de continuar em nova conversa.