Criar cartões no Canvas

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.
• 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 <type> [--workspace <selector>] [--agent <id>] [--role <name>]
                          [--model <id>] [--title <text>] [--content <text>]
                          [--content-file <path|->] [--position <x,y>] [--size <w,h>]
                          [--link-to <nodeId>] [--orchestrator] [--path <path>]
                          [--cwd <folder>] [--url <url>] [--device-id <id>]
                          [--platform <android|ios>] [--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;
• 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 <card> 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.