Messages between agents

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

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

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

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.