--- id: "canvas.cartao-conversa" titulo: "A conversa no Canvas" resumo: "Como funciona o cartão de conversa do quadro, o que ele tem de próprio e como dirigi-lo pela linha de comando." idioma: "pt-br" tipo: "conceito" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["chat.canvas.list", "chat.canvas.send", "chat.canvas.read"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/pt-br/canvas/cartao-conversa/" fonte: "pt-br/canvas/cartao-conversa.md" caminhoPublico: "docs/publica/pt-br/canvas/cartao-conversa.md" hashFonte: "sha256:d31c48933b898c3aaf7798262e51b759dc6c6c05b0223d0277f98867955793a5" hashDestaPagina: "sha256:d31c48933b898c3aaf7798262e51b759dc6c6c05b0223d0277f98867955793a5" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- 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 ] [--json] elyra chat send --chat (--text | --text-file ) [--json] elyra chat read --chat [--limit ] [--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. |