--- id: "canvas.criar-cartoes" titulo: "Criar cartões no Canvas" resumo: "Abra conversa, terminal, nota, grupo de notas, navegador ou celular no quadro — pelo topo, pelo clique direito e pela linha de comando." idioma: "pt-br" tipo: "guia" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["canvas.cards.create", "canvas.cards.birth-role"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/pt-br/canvas/criar-cartoes/" fonte: "pt-br/canvas/criar-cartoes.md" caminhoPublico: "docs/publica/pt-br/canvas/criar-cartoes.md" hashFonte: "sha256:f9314fdc6512ee7f76ff4f009575a9f69f257b52b89047c56614940505c294bd" hashDestaPagina: "sha256:f9314fdc6512ee7f76ff4f009575a9f69f257b52b89047c56614940505c294bd" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- Há dois caminhos para criar um cartão: a **barra no topo** do quadro e o **clique direito no fundo**. Os dois criam o mesmo tipo de cartão; o clique direito tem a vantagem de já posicionar o cartão no ponto que você apontou. ## Pela barra do topo A barra oferece **Conversa**, **Terminal**, **Nota** (com submenu **Nota** e **Grupo de notas**), **Navegador** e **Celular**. - **Conversa** abre um seletor de assistente antes de criar o cartão: escolher o assistente é parte da criação, não um passo depois. - **Terminal** oferece um shell puro ou um terminal já com um assistente. - **Nota** cria um cartão de nota vazio; o **Grupo de notas** cria o fichário. Os dois estão detalhados em [Notas no Canvas](/docs/pt-br/canvas/notas/visao-geral/). - **Celular** fica **desabilitado** quando o emulador não está disponível na build, com o aviso "Emulador ainda não disponível nesta versão". ## Pelo clique direito no fundo Com o clique direito no fundo do quadro, o item **"Adicionar aqui"** cria o cartão onde você apontou. Para **Conversa** e **Terminal** ele abre um submenu para escolher o assistente. O cartão de **Arquivo** não está nessa lista nem na barra: ele nasce quando você abre um arquivo real do projeto, e reaproveita a mesma fila de abertura da tela Arquivos. ## Quem pode criar cartões de agente Só o **cartão orquestrador** cria cartões de **Conversa** e **Terminal**. Um cartão sem esse papel que pede um agente é recusado, e o pedido deve ser encaminhado ao orquestrador. A exceção existe para o quadro nunca travar: **o primeiro cartão de agente de um Canvas vazio nasce orquestrador**. Um Canvas novo, portanto, sempre tem por onde começar. Cartões de nota, arquivo, navegador e celular não são agentes e qualquer pessoa pode criá-los. ## Pela linha de comando Um agente pode criar cartões sem tocar na interface: ``` elyra canvas create [--workspace ] [--agent ] [--role ] [--model ] [--title ] [--content ] [--content-file ] [--position ] [--size ] [--link-to ] [--orchestrator] [--path ] [--cwd ] [--url ] [--device-id ] [--platform ] [--json] ``` O tipo é um de `chat`, `terminal`, `note`, `file`, `browser`, `device`. As flags são específicas por tipo e passar a flag errada para o tipo errado é recusado: | Tipo | Flags próprias | Observações | |---|---|---| | `chat` | `--agent`, `--model` | O modelo é escolhido aqui e só aqui. | | `terminal` | `--agent`, `--cwd` | `--model` **não** é aceito: o assistente roda a própria interface e não há forma uniforme de escolher o modelo no lançamento. | | `note` | `--content`, `--content-file`, `--title` | Escreve o arquivo `.md` já no nascimento. | | `file` | `--path` (obrigatório) | O caminho é relativo à raiz do workspace e **o arquivo precisa existir**. | | `browser` | `--url` | Define a página inicial do cartão. | | `device` | `--device-id`, `--platform` | Aceita `android` ou `ios`. | Regras que evitam surpresa: - `--position` e `--size` levam dois números separados por vírgula: `"400,120"` e `"900,600"`. - `--link-to` liga o cartão novo a um cartão existente (por id ou título exato). Sem a flag, o cartão já nasce ligado a **quem chamou**, quando existe um cartão chamador. - `--orchestrator` é açúcar para `--role orquestrador`; passar os dois é erro. - Criar um cartão de celular **não** liga o emulador: o cartão é só o lugar onde ele vai aparecer. ### O que o comando devolve Cada tipo devolve um identificador próprio, que é o que os comandos seguintes usam: - `terminal` devolve a sessão, e ela passa a aparecer na lista de terminais; - `chat` devolve um **handle estável** (no formato `chat_<12 hex>`), que não aparece na lista de terminais — veja [A conversa no Canvas](/docs/pt-br/canvas/cartao-conversa/); - `note` devolve o caminho absoluto real do arquivo `.md`, que fica **fora da pasta do projeto**; - os demais devolvem o identificador do cartão. ### Papel declarado na criação A flag `--role` **declara** o papel pretendido, mas o papel nomeado ainda não é aplicado no momento da criação: até essa ligação fechar, o cartão nasce **sem papel** e você o promove depois com `elyra canvas set-orchestrator ` ou com o diálogo de papéis. A exceção é a automática: o primeiro cartão de agente de um Canvas vazio nasce orquestrador. ## Depois de criar: o que esperar - **Um terminal não fica pronto na hora.** Ele leva alguns segundos (a medição conhecida é da ordem de 7 segundos em Windows) até aparecer na lista de terminais e aceitar entrada. Até lá ele não aparece em lugar nenhum — **não recrie o cartão**. - **Uma sessão de conversa não aparece na lista de terminais.** Ela roda pelo SDK, com endereço próprio. - **A pasta de um terminal precisa existir.** Se o diretório pedido em `--cwd` não existir quando o terminal subir, ele abre na pasta do workspace e diz isso nas primeiras linhas; a raiz de um disco é recusada antes de criar o cartão. Crie o diretório primeiro. ## Recuperação e limpeza - **Nota criada sem arquivo.** Se o arquivo da nota não puder ser criado, o cartão aparece no Canvas e o aviso diz **onde** o Elyra tentou gravar e por quê. O texto que você escrever ali pode não ser salvo — confira o caminho informado antes de confiar na nota. - **Cartão criado por engano.** Feche pelo botão de fechar do cartão. Atenção: fechar um terminal **encerra a sessão** e fechar uma nota **apaga o arquivo**. - **Terminal que não aparece.** Espere o tempo de subida antes de qualquer coisa; recriar o cartão deixa dois terminais e dois processos onde você queria um.