---
id: "fluxos.orquestracao-mensagens"
titulo: "Messages between agents"
resumo: "Send, read and reply to messages between linked agents, with a type and a priority that say what the message is."
idioma: "en"
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/en/fluxos/orquestracao-mensagens/"
fonte: "pt-br/fluxos/orquestracao-mensagens.md"
caminhoPublico: "docs/publica/en/fluxos/orquestracao-mensagens.md"
hashFonte: "sha256:20ecc8b59ca1f680654d0615b1630cc16028f4db9668ed028d1409d52a98d204"
hashDestaPagina: "sha256:a185bac42ef25791f3623c1ecd59ed414c7f7c818848502b9deeea1cb878d3b6"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/fluxos/orquestracao-mensagens.md fonteHash=sha256:20ecc8b59ca1f680654d0615b1630cc16028f4db9668ed028d1409d52a98d204 estado=atual -->

Agents linked on the Canvas exchange messages through a box of their own, independent of the terminal
text. It is through there that a child says it has finished, that a conductor asks for a decision, and
that two peers agree on what to do with a file.

## Sending

```bash
elyra orchestration send --to <handle|title> --subject "<text>" [--body <text>|--body-file <path>]   [--type <tipo>] [--priority <level>] [--from <handle|title>]
```

- **`--to` and `--from`** accept an address or the **card title**, with the same effect.
- **A title repeated in two cards is refused**, with the list of the candidates: rename one of them. It
  is better to fail than to deliver to the wrong conversation.
- **`--subject`** is the subject; **`--body`** is the body. Use **`--body-file`** for text with several
  lines: on Windows, the multiline `--body` is cut at the first line break by the terminal shortcut.
- **`--payload`** accepts JSON, for structured data.

### Message types

The type is not decorative — it is what makes the recipient know whether it needs to act:

| Type | What it is for |
|---|---|
| `status` | Progress update; it is the type for news in general |
| `worker_done` | "I finished what was handed to me" — **it needs a concrete address** |
| `merge_ready` | The work is ready for integration |
| `escalation` | It needs a decision from whoever coordinates |
| `handoff` | Hands over the context and the responsibility to another agent |
| `decision_gate` | Opens a decision **without blocking** whoever asked |
| `heartbeat` | "I am still alive" — **it needs a concrete address** |

`worker_done` and `heartbeat` require a concrete coordinating terminal: they wake someone, and a diffuse
address has no one to wake. For news in general, use `status`.

### Priority

`--priority` accepts `normal`, `high` and `urgent`. Use priority to say **how long that can wait**, not
to repeat the request.

## Reading

```bash
elyra orchestration check [--terminal <handle|title>] [--unread | --all] [--types <type,...>] [--wait]
```

- **Without flags**, it returns the **unread** messages and marks them as read.
- **`--all`** returns all the messages of that terminal and does **not** mark anything as read.
- **`--types`** filters by type — it is how a coordinator sees only what needs it
  (`--types worker_done,escalation`).
- **`--wait`** blocks until a message that matches arrives or until the time limit passes. Each listed
  message carries the **id** you use to reply.

Two traps of `--wait`, which exist so that you do not break your own script:

1. **It emits heartbeat lines on the error channel** every 15 seconds, so that the process that called
   it knows it is alive. When merging the two outputs, filter them.
2. **The maximum waiting time is one hour.** Waiting is not free: while the process waits, it is
   occupying the agent.

## Replying

```bash
elyra orchestration reply --id <message-id> [--body <text>|--body-file <path>]
```

The reply **does not block** whoever replies: it is delivered and the agent goes on working. The id
comes from the listing — reply to the right id, because there is no confirmation that the recipient read
it.

## Cleanup

`orchestration check` **marks as read** what it returns by default. If you want to re-read without
consuming, use `--all`. There is no command to delete a single message; deleting the whole state is
destructive.

## Scope and limits

- **Reach.** An agent reaches the cards linked to it in the same workspace. If the list of titles comes
  truncated, a namesake out of reach is not seen — and the delivery warns about the cut.
- **Delivery is not reading.** A message delivered to the recipient's terminal does not mean that the
  agent read it or acted on it.
- **The address changes.** The Canvas changes while the work happens; check the neighbours before
  sending.