Pattern orchestratore-sottoagente
Implementi il pattern orchestratore-sottoagente, in cui un agente pianificatore suddivide le attività in sottoattività, le delega ad agenti specializzati e sintetizza i risultati in un output finale.
Pattern orchestratore-sottoagente è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Il modello mentale orchestratore-sottoagente
Il pattern orchestratore-sottoagente è l'architettura multi-agente più utilizzata. Un agente orchestratore riceve un obiettivo di alto livello, lo scompone in sottoattività, assegna ogni sottoattività a un sottoagente specializzato, raccoglie i risultati e sintetizza un output finale. Consideri l'orchestratore come un responsabile di progetto e i sottoagenti come esperti del dominio all'interno del team.
Responsabilità dell'orchestratore
L'orchestratore ha tre responsabilità fondamentali: scomposizione (suddividere l'obiettivo in sottoattività concrete e attuabili), delega (assegnare ogni sottoattività allo specialista giusto) e sintesi (combinare gli output dei sottoagenti in un risultato coerente). L'orchestratore svolge un lavoro minimo specifico del dominio: il suo valore risiede nel coordinamento.
from openai import OpenAI
client = OpenAI()
def orchestrator(goal: str) -> dict:
# Step 1: Decompose
plan = client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'system', 'content': 'You are a task planner. Decompose the goal into subtasks. Return JSON with keys: researcher_task, writer_task, coder_task.'},
{'role': 'user', 'content': goal}
],
response_format={'type': 'json_object'}
)
return plan.choices[0].message.contentProgettazione di sottoagenti specializzati
Ogni sottoagente è ottimizzato per una singola responsabilità. La specializzazione comprende: un prompt di sistema mirato che definisce il ruolo, un insieme ristretto di strumenti (3-5) pertinenti esclusivamente a quel ruolo e una finestra di contesto che contiene solo le informazioni necessarie per quella sottoattività. Gli agenti focalizzati prendono decisioni migliori e sono più facili da valutare e sottoporre a debug.
def create_researcher_agent():
return {
'model': 'gpt-4o',
'system': '''You are a research specialist. Your only job is to find accurate,
cited information. Return structured findings with sources.
Do NOT write prose or code - only research findings.''',
'tools': ['search_web', 'fetch_url', 'query_arxiv'], # 3 tools only
'max_iterations': 10
}
def create_writer_agent():
return {
'model': 'gpt-4o',
'system': '''You are a technical writer. Transform research findings into clear,
engaging prose. You receive structured data and return polished text.''',
'tools': ['format_markdown', 'check_readability'], # 2 tools only
'max_iterations': 5
}Il protocollo di delega
Perché la delega funzioni, l'orchestratore deve passare a ogni subagente pacchetti di attività ben formati. Un pacchetto di attività include: l'obiettivo specifico del subagente, il contesto rilevante di cui ha bisogno (non l'intera cronologia della conversazione), il formato di output previsto e gli eventuali vincoli. I pacchetti di attività mal formati sono la causa più comune dei problemi tra orchestratore e subagenti.
from dataclasses import dataclass
from typing import Optional
@dataclass
class TaskPacket:
task_id: str
assignee: str # which subagent receives this
goal: str # specific, actionable goal
context: str # only relevant background
output_format: str # JSON schema or description
constraints: list[str] # e.g. ['max 500 words', 'cite sources']
deadline_steps: int # max iterations allowed
def delegate(packet: TaskPacket, subagent_fn) -> str:
prompt = f'Goal: {packet.goal}\nContext: {packet.context}\nOutput format: {packet.output_format}\nConstraints: {packet.constraints}'
return subagent_fn(prompt)Raccolta e sintesi dei risultati
Quando i subagenti hanno completato il loro lavoro, l'orchestratore deve sintetizzare i risultati. Non si tratta di una semplice concatenazione. L'orchestratore deve risolvere i conflitti tra gli output dei subagenti, colmare le lacune, mantenere uno stile o un formato coerente e produrre un risultato finale complessivamente organico. È nella fase di sintesi che la capacità di ragionamento dell'orchestratore è più necessaria.
def synthesize_results(research: str, draft: str, code: str, goal: str) -> str:
synthesis_prompt = f'''You are given outputs from three specialist agents.
Your job is to synthesize them into one coherent final answer for this goal: {goal}
RESEARCH FINDINGS:
{research}
WRITTEN DRAFT:
{draft}
CODE EXAMPLES:
{code}
Resolve any conflicts, fill gaps, and produce a unified final response.
'''
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': synthesis_prompt}]
)
return response.choices[0].message.contentDelega sequenziale e parallela
Gli orchestratori possono delegare le attività in sequenza (l'output di un subagente alimenta quello successivo) oppure in parallelo (più subagenti lavorano simultaneamente). La delega sequenziale è più semplice e funziona quando i passaggi successivi dipendono dai risultati precedenti. La delega parallela è più rapida quando le sottoattività sono indipendenti e possono essere eseguite contemporaneamente, spesso riducendo il tempo effettivo di esecuzione di 3-5 volte.
import asyncio
# Sequential: writer needs research first
async def sequential_pipeline(goal):
research = await researcher_agent(goal)
draft = await writer_agent(research) # depends on research
return draft
# Parallel: all three tasks are independent
async def parallel_pipeline(topics):
tasks = [
researcher_agent(topics[0]),
researcher_agent(topics[1]),
researcher_agent(topics[2])
]
results = await asyncio.gather(*tasks) # runs simultaneously
return orchestrator_synthesize(results)Gestione dei problemi dei subagenti
I subagenti possono occasionalmente avere dei problemi: possono restituire un output malformato, superare il proprio limite di iterazioni o riscontrare un errore. L'orchestratore deve gestire questi problemi in modo appropriato. Le strategie più comuni includono: riprovare con un pacchetto di attività più chiaro, ricorrere a un approccio più semplice, saltare la sottoattività non riuscita annotandolo nell'output finale oppure richiedere una revisione umana.
def delegate_with_retry(packet: TaskPacket, subagent_fn, max_retries=2):
for attempt in range(max_retries + 1):
try:
result = subagent_fn(packet)
validate_output(result, packet.output_format)
return result
except ValidationError as e:
if attempt < max_retries:
# Clarify the task for retry
packet.goal += f'\n\nPrevious attempt failed: {str(e)}. Please fix.'
print(f'Retry {attempt + 1} for task {packet.task_id}')
else:
return {'error': str(e), 'task_id': packet.task_id, 'status': 'failed'}Scrivere prompt efficaci per l'orchestratore
Il prompt di sistema dell'orchestratore è fondamentale per la qualità dell'intera pipeline. Deve definire chiaramente: quali subagenti sono disponibili e in cosa è specializzato ciascuno, come formattare i pacchetti di attività, quando eseguire le sottoattività in parallelo o in sequenza, come gestire risultati incompleti o in conflitto e che cosa costituisce un output finale valido.
ORCHESTRATOR_SYSTEM_PROMPT = '''
You coordinate a team of specialist agents to complete complex tasks.
Available agents:
- researcher: Finds and cites factual information. Input: question string. Output: JSON with findings and sources.
- writer: Writes polished prose from structured data. Input: JSON findings. Output: markdown text.
- coder: Writes Python code. Input: natural language spec. Output: Python code string.
Workflow:
1. Analyze the goal and decide which agents are needed.
2. Identify dependencies: can any tasks run in parallel?
3. Delegate tasks with clear, specific goals.
4. Validate each result before proceeding.
5. Synthesize all results into a unified final answer.
'''L'isolamento del contesto è un vantaggio
Un vantaggio importante del pattern orchestratore-subagente è l'isolamento del contesto. Ogni subagente vede solo le informazioni rilevanti per la propria sottoattività, non l'intera cronologia del progetto. Questo mantiene ridotta la finestra di contesto di ogni subagente, evitando l'esaurimento del contesto che affligge gli agenti singoli. L'orchestratore mantiene la visione globale, mentre i subagenti mantengono visioni locali e mirate.
Tracciamento e osservabilità
I sistemi multi-agente sono più difficili da sottoporre a debug rispetto agli agenti singoli, perché gli errori possono verificarsi in qualsiasi passaggio della delega. Aggiungete sempre il logging strutturato per tenere traccia di: quali attività sono state delegate, a quale subagente, quali erano l'input e l'output, quanto tempo ha richiesto ciascuna attività e se sono stati necessari nuovi tentativi. Strumenti come LangSmith e Langfuse supportano la visualizzazione delle tracce dei sistemi multi-agente.
import time
def logged_delegate(packet: TaskPacket, subagent_fn):
start = time.time()
print(f'[DELEGATE] task_id={packet.task_id} assignee={packet.assignee}')
print(f'[INPUT] {packet.goal[:100]}...')
result = subagent_fn(packet)
elapsed = time.time() - start
print(f'[RESULT] task_id={packet.task_id} elapsed={elapsed:.2f}s')
print(f'[OUTPUT] {str(result)[:100]}...')
return resultPattern reale: generatore di report
Un esempio concreto del pattern orchestratore-subagente è un generatore di report di analisi della concorrenza. L'orchestratore riceve la richiesta «Scriva un'analisi della concorrenza per l'azienda X». Delega: la sottoattività di ricerca a un agente ricercatore (che individua prezzi, funzionalità e recensioni), la sottoattività di analisi a un agente analista (che identifica punti di forza e debolezza) e la sottoattività di formattazione a un agente scrittore (che produce il report finale). Ogni specialista fa ciò che sa fare meglio.
Verifica rapida
Verifichi la Sua comprensione del pattern orchestratore-subagente illustrato in questa lezione.
Riepilogo della lezione
In questa lezione ha imparato che: il pattern orchestratore-subagente utilizza un agente coordinatore per scomporre e delegare il lavoro a specialisti; i pacchetti di attività devono definire chiaramente obiettivo, contesto e formato di output previsto affinché la delega funzioni; e l'isolamento del contesto mantiene ridotta la finestra di ogni subagente, mentre l'orchestratore conserva la visione globale. Nella prossima lezione costruiremo pipeline multi-agente con LangGraph.
Impara Python con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 30
- Lezioni
- 120
Domande Frequenti
La lezione «Pattern orchestratore-sottoagente» è gratuita?
Sì — il testo completo di «Pattern orchestratore-sottoagente» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Pattern orchestratore-sottoagente»?
Implementi il pattern orchestratore-sottoagente, in cui un agente pianificatore suddivide le attività in sottoattività, le delega ad agenti specializzati e sintetizza i risultati in un output finale. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Pattern orchestratore-sottoagente»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Perché gli agenti singoli arrivano a un limite
- Pattern orchestratore-sottoagente
- Creare pipeline multi-agente con LangGraph
- Memoria condivisa e comunicazione tra agenti