---
id: "fluxos.orquestracao-mensagens"
titulo: "Mensagens entre agentes"
resumo: "Envie, leia e responda mensagens entre agentes ligados, com tipo e prioridade que dizem o que a mensagem é."
idioma: "pt-br"
tipo: "guia"
categoria: "agentes"
aplicavelDesde: "0.0.16"
capabilities: ["orchestration.messages.send", "orchestration.messages.check", "orchestration.messages.reply"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/fluxos/orquestracao-mensagens/"
fonte: "pt-br/fluxos/orquestracao-mensagens.md"
caminhoPublico: "docs/publica/pt-br/fluxos/orquestracao-mensagens.md"
hashFonte: "sha256:20ecc8b59ca1f680654d0615b1630cc16028f4db9668ed028d1409d52a98d204"
hashDestaPagina: "sha256:20ecc8b59ca1f680654d0615b1630cc16028f4db9668ed028d1409d52a98d204"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
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

```bash
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

```bash
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

```bash
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.