--- id: "canvas.cartao-conversa" titulo: "The conversation on the Canvas" resumo: "How the board's conversation card works, what is its own, and how to drive it from the command line." idioma: "en" 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/en/canvas/cartao-conversa/" fonte: "pt-br/canvas/cartao-conversa.md" caminhoPublico: "docs/publica/en/canvas/cartao-conversa.md" hashFonte: "sha256:d31c48933b898c3aaf7798262e51b759dc6c6c05b0223d0277f98867955793a5" hashDestaPagina: "sha256:fe69f6b5490bf0a86f7cd3ebebeafd6f448245025b8e7d57162f955b1ccb51b0" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- The **Conversation** card is where a conversation with an assistant lives inside the board. It is one of the product's conversation surfaces — and it is **not the same thing** as a conversation on the Conversation screen. ## A place of its own The product decision is that the screens are independent: **a conversation on the Canvas is not the Conversation screen's conversation seen from another angle**. The two surfaces keep separate conversations, each with its own session. > **Mind the expectation.** Do not count on "the Conversation screen's conversation appears on the Canvas" — nor on the opposite — as guaranteed behavior. Treat the two as distinct places. What that means in practice: opening a conversation card on the board **creates** a conversation there. It is not the same one you had open on the other screen. ## The main conversation card is the maestro The project's main conversation card is the **orchestrator**: when it creates child agents, each child appears as a card linked to it by a line. ## The session - **The session lives in the app's main process.** Changing the layout, minimizing the card or switching screens does **not** interrupt the conversation. - **The session does not appear in the terminal list.** A conversation runs through the SDK, with an address of its own — looking for it among the terminals finds nothing. That is expected, not a defect. - **An idle conversation may be reaped and recreated.** After a period of no use, the idle session is ended to free resources and **recreated on the next send**. That is why a stopped conversation does not cost a process forever. - **The draft is preserved.** Text you wrote and have not sent yet is stored per conversation: it survives switching screens, minimizing, reloading the window and restarting the app. If the conversation ends, the card shows what you had written, with the **Copy** and **Continue in a new conversation** options. - **Closing the card ends the conversation** and that conversation's draft is discarded with it. ## The conversation's assistant The assistant is chosen **at card creation**, and so is the model: `--model` is accepted on the conversation card and **only** there. Elyra's conversation path is the **SDK** path, not typing into a terminal. Where the SDK cannot drive the assistant, the screen **says the conversation is unavailable there** — it never falls back to a terminal interface on its own. On a **remote worktree (SSH)**, the SDK path crosses the connection. The other assistants follow the terminal path and are **not** local by construction in that scenario. > **The assistant choice changes what exists afterwards.** Not every combination of assistant and host offers the same set of features in the conversation. What the screen shows is conditioned on what that adapter offers — there is no universal parity between providers. ## Driving the conversation from the command line A conversation card has a **stable address**, derived from the conversation's tab, in the `chat_<12 hex>` format. It is the same after reloading the window, restarting the app and moving the card, and it never collides with a terminal's address. ``` elyra chat list [--workspace ] [--json] elyra chat send --chat (--text | --text-file ) [--json] elyra chat read --chat [--limit ] [--json] ``` The list brings the conversation cards of that workspace's Canvas, with handle, card id, assistant, title and a working indicator. **It is not the Conversation screen:** that screen's conversations do not appear here. The send accepts a handle, tab id, card id or the **exact title**. A repeated title does **not** identify a target: the runtime asks you to list and disambiguate. Prefer the handle. ### What the send response means The response is `{ok: true, handle, queued}`. > **`queued: true` means the turn was already in progress and the message was enqueued — not that the assistant replied.** A confirmed send is the send, not the reply. To see the reply, read the conversation. ### What the read brings The read is a **simplified projection**: each message comes as `{role, text, at}`. Blocks that are not text — the assistant's reasoning and tool calls — **do not appear** in that output. The response carries `truncated: true` when older messages were dropped. ## Limits worth knowing now - **The session must be alive to receive a message.** A card whose view has not mounted yet **has no session** in the main process, and the send is refused with a message saying exactly that. In practice: open the Canvas so the card mounts, and repeat the send. **The send does not create the session on its own.** - **Because of that, an orchestration child should be a terminal card, not a conversation card.** A terminal is born without depending on the view being mounted and receives the task through its address. The conversation card serves the conversation that **you** follow. - **The list may show cards the send cannot reach.** The send and read path looks for the managed session in the main process: it exists for cards that run through the SDK. A card from another assistant may appear in the list without being reachable by the send. - **The conversation does not appear in the terminal list.** That is a consequence of running through the SDK, not a missing card. - **A repeated title is not an address.** Use the handle or the card id in any automation. ## Recovery | Situation | What to do | |---|---| | The send refuses saying the session does not exist | Open the Canvas so the card mounts and repeat the send. | | The card's name is ambiguous | List the cards with `--json` and use the handle. | | The read does not bring the reasoning or the tools | Expected: the command-line read projects text only. Use the card on screen for the full conversation. | | The conversation ended and you had written text | The card shows the draft; use **Copy** before continuing in a new conversation. |