Orchestrare gli agenti usando flussi di lavoro di GitHub
Una volta chiarite le responsabilità, l’attenzione si sposta su come gli agenti coordinano il loro lavoro. Anche i ruoli ben definiti possono causare confusione se l'esecuzione non è strutturata. Pensa a quando gli agenti devono essere eseguiti, a come viene sequenziato il loro lavoro e a come gli output passano tra le fasi. Esprimere questo coordinamento tramite flussi di lavoro GitHub mantiene il sistema prevedibile, osservabile e più facile da gestire man mano che cresce.
In questa unità, imparerai
In che modo gli eventi di GitHub coordinano il comportamento dell'agente
Come progettare l'orchestrazione sequenziale e parallela
Come usare gli artefatti per il coordinamento invece della comunicazione diretta
Perché l'orchestrazione deve rimanere osservabile
Che cos'è l'orchestrazione nei sistemi multi-agente
L'orchestrazione nei sistemi multi-agente definisce il modo in cui più agenti coordinano il lavoro all'interno di un ambiente condiviso. Determina quando gli agenti entrano in esecuzione, come le loro attività vengono messe in sequenza e come i risultati vengono trasferiti tra le varie fasi, garantendo che il lavoro proceda in modo controllato e prevedibile anziché in modo indipendente o in conflitto.
Come funziona l'orchestrazione in GitHub
In GitHub l'orchestrazione funziona meglio quando viene espressa tramite flussi di lavoro che rispondono agli eventi. In questo modo il coordinamento viene mantenuto visibile perché si verifica nelle richieste pull, nelle esecuzioni del flusso di lavoro, nei controlli e nei log.
I trigger tipici includono:
pianificazioni per il lavoro periodico (creazione di report, controlli delle dipendenze),
eventi di pull request per la convalida e l'iterazione, e
il completamento del flusso di lavoro viene attivato quando un passaggio deve essere eseguito dopo un altro.
Ciò è importante perché il coordinamento nascosto rende impossibile diagnosticare gli errori.
Orchestrazione sequenziale
Alcune operazioni devono essere eseguite in una sequenza rigorosa. Una pipeline tipica è:
- L'agente delle dipendenze apre una PR.
- CI verifica la correttezza (test/build).
- Un flusso di lavoro di verifica della sicurezza viene eseguito dopo il completamento della CI.
- Un revisore umano approva.
- L'unione avviene solo quando tutti i criteri sono soddisfatti.
Esempio: esegui la convalida di sicurezza dopo il completamento della CI:
\# File: .github/workflows/security-validate.yml
name: Security Validation
on:
workflow_run:
workflows: [CI Validation]
types: [completed]
jobs:
validate:
runs-on: ubuntu-latest
steps:
\- run: echo "Run security validation here."
Usare questo modello quando l'output di un agente deve essere convalidato prima che un altro passaggio possa procedere.
Orchestrazione parallela
L'orchestrazione parallela è appropriata quando i limiti dell'ambito impediscono la sovrapposizione. Ad esempio, un agente di documentazione e un agente di refactoring possono funzionare contemporaneamente se operano in percorsi separati. I risultati confluiscono ancora attraverso i controlli e le revisioni delle pull request.
Il requisito di progettazione principale per l'orchestrazione parallela è l'isolamento: se gli agenti possono scontrarsi sugli stessi file, il parallelismo aumenterà l'instabilità anziché la velocità effettiva.
Esempio: modello di orchestrazione Fan-Out, Fan-In
Per coordinare più agenti in parallelo e quindi unire gli output, usare l'orchestrazione fan-out/fan-in con le esigenze. Questo modello viene testato nell'esame ed è una procedura consigliata per la composizione di fasi di analisi/revisione/unione.
name: multi-agent-orchestration
on:
workflow_dispatch:
jobs:
spec_analyzer:
runs-on: ubuntu-latest
steps:
- name: Run spec analyzer
run: ./executors/spec_analyzer.sh
risk_reviewer:
runs-on: ubuntu-latest
steps:
- name: Run risk reviewer
run: ./executors/risk_reviewer.sh
plan_merger:
runs-on: ubuntu-latest
needs: [spec_analyzer, risk_reviewer] # <--- FANS IN both
steps:
- name: Merge analysis and risk outputs
run: ./executors/plan_merger.sh
- name: Publish merged plan
run: echo "publish plan artifact"
concurrency:
group: multiagent-${{ github.ref }} # <-- Ensures no overlapping merge jobs per branch
Ciò garantisce che plan_merger attenda entrambi i job a monte, un classico "fan-in".
Coordinamento basato su artefatti
Nei sistemi multi-agente, la comunicazione diretta da agente a agente è spesso meno affidabile rispetto agli artefatti verificabili condivisi. Un modello di orchestrazione affidabile consiste nel:
- eseguire un agente con autorizzazioni limitate,
- produrre un output strutturato (piano/relazione/proposta) come artefatto e quindi
- usare un passaggio controllato per applicare solo le operazioni consentite dal flusso di lavoro.
Questo modello crea un limite esplicito tra "ragionamento" e "scrittura" e lascia prove che i revisori possono esaminare.
Esempio: report pianificato del repository (artefatto + output controllato)
# File: .github/workflows/daily-repo-report.yml
name: Daily Repo Status Report
on:
schedule:
- cron: "0 2 * * *"
permissions:
contents: read
issues: write
pull-requests: read
jobs:
report:
runs-on: ubuntu-latest
steps:
- name: Generate report
run: |
echo '{ "summary": "Daily status...", "links": [] }' > report.json
- name: Upload report artifact
uses: actions/upload-artifact@v4
with:
name: repo-status-report
path: report.json
- name: Create issue (controlled output)
run: |
echo "Create issue from report.json"
Cosa accade quando l'orchestrazione è nascosta
Se il coordinamento si verifica all'esterno di GitHub e non lascia prove nelle richieste pull o nelle esecuzioni del flusso di lavoro, i revisori perdono la capacità di capire perché il sistema si comportava nel modo in cui ha funzionato. Ciò rende più difficile diagnosticare i guasti e riduce la fiducia.
Punto chiave
L'orchestrazione deve essere espressa tramite gli eventi di GitHub Actions e gli artefatti condivisi, in modo che il sistema rimanga osservabile. Usare l'orchestrazione sequenziale quando gli output dipendono dai passaggi precedenti. Usare l'orchestrazione parallela solo quando gli agenti operano su percorsi isolati.
Una volta coordinati i flussi di lavoro, è necessario assicurarsi che gli agenti non interferiscano tra loro durante l'esecuzione.