Mensagens entre agentes

Agentes ligados no Canvas trocam mensagens por uma caixa própria, independente do texto do terminal. É por ali que um filho avisa que terminou, que um maestro pede uma decisão, e que dois pares combinam o que fazer com um arquivo.

Enviar

elyra orchestration send --to <handle|título> --subject "<texto>" [--body <texto>|--body-file <caminho>]   [--type <tipo>] [--priority <nível>] [--from <handle|título>]

• --to e --from aceitam um endereço ou o título do cartão, com o mesmo efeito.
• Título repetido em dois cartões é recusado, com a lista dos candidatos: renomeie um deles. É melhor falhar do que entregar na conversa errada.
• --subject é o assunto; --body é o corpo. Use --body-file para texto com várias linhas: no Windows, o --body multilinha é cortado na primeira quebra de linha pelo atalho do terminal.
• --payload aceita JSON, para dados estruturados.

Tipos de mensagem

O tipo não é decorativo — é ele que faz o destinatário saber se precisa agir:

Tipo	Para que serve
status	Atualização de andamento; é o tipo para novidades em geral
worker_done	“Terminei o que me foi passado” — precisa de um endereço concreto
merge_ready	O trabalho está pronto para integração
escalation	Precisa de uma decisão de quem coordena
handoff	Passa o contexto e a responsabilidade para outro agente
decision_gate	Abre uma decisão sem bloquear quem perguntou
heartbeat	“Continuo vivo” — precisa de um endereço concreto

worker_done e heartbeat exigem um terminal coordenador concreto: eles acordam alguém, e um endereço difuso não tem quem acordar. Para novidades em geral, use status.

Prioridade

--priority aceita normal, high e urgent. Use a prioridade para dizer quanto aquilo pode esperar, não para repetir o pedido.

Ler

elyra orchestration check [--terminal <handle|título>] [--unread | --all] [--types <tipo,...>] [--wait]

• Sem flags, ele devolve as mensagens não lidas e as marca como lidas.
• --all devolve todas as mensagens daquele terminal e não marca nada como lido.
• --types filtra por tipo — é como um coordenador vê só o que precisa dele (--types worker_done,escalation).
• --wait bloqueia até chegar uma mensagem que case ou até o tempo limite passar. Cada mensagem listada traz o id que você usa para responder.

Duas armadilhas de --wait, que existem para você não quebrar o seu próprio script:

1. Ele emite linhas de batimento no canal de erro a cada 15 segundos, para o processo que chamou saber que ele está vivo. Ao juntar as duas saídas, filtre-as.
2. O tempo máximo de espera é de uma hora. Esperar não é gratuito: enquanto o processo espera, ele está ocupando o agente.

Responder

elyra orchestration reply --id <id-da-mensagem> [--body <texto>|--body-file <caminho>]

A resposta não bloqueia quem responde: ela é entregue e o agente segue trabalhando. O id vem da listagem — responda ao id certo, porque não há confirmação de que o destinatário leu.

Limpeza

orchestration check marca como lido o que devolve por padrão. Se você quer reler sem consumir, use --all. Não há comando para apagar uma mensagem isolada; apagar o estado inteiro é destrutivo.

Escopo e limites

• Alcance. Um agente alcança os cartões ligados a ele no mesmo workspace. Se a lista de títulos vier truncada, um homônimo fora de alcance não é visto — e a entrega avisa do corte.
• Entrega não é leitura. Uma mensagem entregue no terminal do destinatário não significa que o agente a leu ou agiu sobre ela.
• Endereço muda. O Canvas muda enquanto o trabalho acontece; consulte os vizinhos antes de enviar.