---
id: "fluxos.orquestracao-conceito"
titulo: "Orquestração: o maestro e os cartões ligados"
resumo: "Entenda como o Elyra organiza vários agentes: o maestro, os filhos ligados a ele no Canvas e o que uma ligação significa."
idioma: "pt-br"
tipo: "conceito"
categoria: "agentes"
aplicavelDesde: "0.0.16"
capabilities: ["orchestration.peers.discover"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/fluxos/orquestracao-conceito/"
fonte: "pt-br/fluxos/orquestracao-conceito.md"
caminhoPublico: "docs/publica/pt-br/fluxos/orquestracao-conceito.md"
hashFonte: "sha256:238910b0b28f1a704ef3f106c94df95a59fd50ada824f1e00471ba19979e8772"
hashDestaPagina: "sha256:238910b0b28f1a704ef3f106c94df95a59fd50ada824f1e00471ba19979e8772"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
Trabalhar com vários agentes de código em paralelo levanta uma pergunta prática: **quem coordena quem**.
No Elyra essa resposta não é um modo que se liga nem um painel separado — ela está na própria conversa.

## O maestro

O cartão de conversa principal de um projeto **é** o orquestrador. Ele não é um tipo especial de
cartão, nem um botão de "distribuir tarefa": o maestro cria os filhos que precisar conversando, com as
skills e a linha de comando do Elyra, e o Canvas apenas mostra o que ele criou.

Quando um filho nasce assim, ele aparece no Canvas **ligado ao maestro por uma linha**, com o estado ao
vivo. É essa linha que faz o Canvas ser um mapa do trabalho em andamento, e não uma pilha de cartões.

## Ligar dois cartões à mão

Você também pode ligar cartões por conta própria, arrastando de um cartão até outro. A ligação fica
desenhada e persistida, e é o que define quem alcança quem.

- **Ligar** dois cartões que já estão ligados não cria uma segunda linha: o painel avisa.
- **Soltar fora de um cartão** não cria nada: o painel avisa que era preciso soltar sobre outro cartão.
- **Ligar um cartão nele mesmo** é recusado.
- **Cartão sem sessão ativa** não pode ser ponta de uma ligação de agente — sem sessão, não há para quem
  entregar mensagem.
- **Remover a ligação** é clique com o botão direito sobre a linha, com confirmação. A linha some; os
  cartões e as sessões continuam como estão.

Uma ligação entre **dois agentes** faz deles pares, que podem trocar mensagens. Uma ligação entre um
**agente e um recurso** — uma nota, um arquivo, uma página do navegador, um aparelho — é contexto: diz
ao agente onde olhar, não cria um par.

## O aviso ao ligar

Em **Ajustes → Orquestração** existe **Avisar ao ligar cartões**. Ele vem **desligado**.

- **Desligado:** a linha no Canvas é toda a ligação. O agente não é avisado.
- **Ligado:** ao ligar, o agente recebe **uma linha** no seu canal de mensagens, dizendo o tipo, o nome
  do recurso e onde olhar. Nunca o conteúdo — o agente lê o recurso sob demanda, se quiser.

O gesto nunca é bloqueado pelo aviso: o fio é desenhado de qualquer forma.

## Descobrir quem está ao seu alcance

Um agente descobre os vizinhos com:

```bash
elyra orchestration peers
```

A resposta lista as relações e os endereços alcançáveis, e a direção de cada uma:

| Direção | Significado |
|---|---|
| `parent` | O cartão que criou este agente |
| `child` | Um cartão que este agente criou |
| `peer` | Uma ligação desenhada à mão |

Duas coisas importantes sobre essa consulta:

1. **Ela é uma fotografia.** O Canvas muda enquanto o trabalho acontece: a ligação que existia na última
   consulta pode ter sido desfeita, e outra pode ter aparecido. Consultar antes de delegar é a regra.
2. **Cartão sem sessão aparece na lista com endereço nulo.** Ele continua ali, marcado como sem sessão —
   não recebe mensagem até ter uma sessão de novo.

## Onde isso se configura

Em **Ajustes → Orquestração** ficam os controles do ciclo de vida dos agentes:

- **Acordar o orquestrador automaticamente** — em cada intervalo, o Elyra envia uma mensagem aos
  cartões com papel de orquestrador, mesmo que o agente esteja trabalhando. Vem **ligado**.
- **Intervalo entre acordadas** — em minutos, com um mínimo e um teto; vale só enquanto o controle acima
  está ligado.
- **Acordar quando um cartão filho finalizar o trabalho** — depois do fim confirmado de um agente, o
  Elyra espera cerca de um segundo e acorda apenas quem **pode ser acordado** e está ligado a ele no
  mesmo workspace.

## Escopo e limites

- **Orquestração não é um modo.** Não existe um botão de "distribuir tarefa" para ligar: o maestro
  delega conversando. Se você procurar esse botão, ele não existe.
- **Ligação é endereço, não permissão.** Estar ligado significa alcançar; o que o agente **pode fazer**
  é assunto de papel, não de linha no Canvas.
- **A ligação vale dentro do workspace.** Um agente não alcança um cartão de outro workspace.

## Próximos passos

- [Mensagens entre agentes](/docs/pt-br/fluxos/orquestracao-mensagens/)