Aggiungere un passaggio dell'agente esistente

Puoi aggiungere agenti AI esistenti come passaggi nel tuo workflow per trasferire le attività ad agenti specializzati. In questo modo puoi comporre workflow multi-agente che orchestrano tra diversi agenti, ognuno dei quali gestisce una parte specifica di un processo più ampio.

Prima di iniziare

Prima di utilizzare questa funzionalità, completa i seguenti passaggi:

  • Assicurati che un amministratore di Gemini Enterprise abbia attivato l'opzione di attivazione/disattivazione di Workflow Builder nelle impostazioni di gestione delle funzionalità dell'app. Per maggiori informazioni, vedi Gestisci le funzionalità dell'app web.

  • Assicurati che gli agenti che vuoi aggiungere siano disponibili nella tua organizzazione. Questa funzionalità supporta l'aggiunta dei seguenti agenti:

Aggiungere un passaggio dell'agente esistente

App

  1. Apri l'app web Gemini Enterprise in un browser.
  2. Vai a un agente esistente o creane uno nuovo.
  3. Nel generatore di flussi, fai clic su Aggiungi passaggio.
  4. Nel riquadro Aggiungi passaggio, fai clic su Agenti esistenti per espandere la sezione.

  5. Sfoglia l'elenco degli agenti disponibili.

  6. Fai clic sull'agente che vuoi aggiungere.

    Il sistema aggiunge il passaggio dell'agente esistente al workflow. L'agente selezionato viene eseguito come parte del workflow, riceve input dai passaggi precedenti e passa l'output ai passaggi successivi.

  7. Nell'area di lavoro, fai clic sul passaggio dell'agente esistente per aprire il relativo riquadro di configurazione e configura quanto segue:

    • Prompt: inserisci il prompt o le istruzioni utilizzate per attivare l' agente. Puoi includere testo statico o fare riferimento agli output dei passaggi precedenti (ad esempio, ${step_name.output}).

Il passaggio dell'agente è un riferimento dinamico all'agente selezionato. Se l'agente di origine viene aggiornato o viene pubblicata una nuova versione, il workflow utilizza automaticamente la versione più recente.

Per maggiori informazioni sulle limitazioni di questa funzionalità, vedi Problemi noti e limitazioni.

Come funzionano le domande di chiarimento

Quando un agente esistente viene eseguito in un workflow, può mettere in pausa l'esecuzione per porre all'utente una domanda di chiarimento se ha bisogno di informazioni mancanti per completare l'attività. Le domande di chiarimento sono supportate in modo nativo quando l'agente a cui viene fatto riferimento emette un segnale input-required (A2A) o un evento RequestInput (ADK).

Quando viene eseguito un passaggio dell'agente esistente e sono necessarie ulteriori informazioni:

  1. L'esecuzione viene messa in pausa: il workflow mette in pausa l'esecuzione al passaggio dell'agente esistente e avvia un prompt human-in-the-loop (HITL).
  2. L'utente risponde al prompt: l'app web Gemini Enterprise mostra all'utente la domanda di chiarimento dell'agente insieme a un campo di testo in cui inserire la risposta.
  3. L'esecuzione riprende: quando l'utente invia la risposta, il workflow riprende l'agente esistente, passando la risposta dell'utente all'agente.
  4. Supporto multi-turno: l'agente può porre più domande di chiarimento di seguito in più turni finché non raccoglie tutte le informazioni richieste e produce l'output finale.

Isolamento del contesto

Durante uno scambio di domande di chiarimento, l'agente a cui viene fatto riferimento riceve solo la propria cronologia delle interazioni con l'utente e il prompt iniziale configurato per il nodo. Gli output e le variabili di altri passaggi del workflow non vengono passati automaticamente all'agente a cui viene fatto riferimento, a meno che non siano esplicitamente indicati nel prompt del passaggio.

Implementare le domande di chiarimento nell'agente

Per supportare le domande di chiarimento, configura l'agente personalizzato in modo che emetta un segnale di input di richiesta a livello di protocollo quando ha bisogno di ulteriori informazioni.

Agenti A2A (nativi)

Per gli agenti che implementano direttamente il protocollo Agent2Agent (A2A), restituisci l'attività nello stato input-required con TaskUpdater, fornendo la domanda di chiarimento nel payload del messaggio:

from a2a.server.tasks import TaskUpdater
from a2a.types import Message, Part, Role, TextPart

# Inside your custom agent's task executor class:
async def execute(self, context, event_queue):
    updater = TaskUpdater(event_queue, context.task_id, context.context_id)
    if context.current_task is None:
        await updater.submit()
    await updater.start_work()

    user_input = context.get_user_input()
    if "weather" in user_input and "tokyo" not in user_input.lower():
        await updater.requires_input(
            Message(
                message_id=f"q-{context.task_id}",
                role=Role.agent,
                parts=[Part(root=TextPart(
                    text="Which city would you like the weather for?"))],
                task_id=context.task_id,
                context_id=context.context_id,
            )
        )
        return

    await updater.complete(
        Message(
            message_id=f"a-{context.task_id}",
            role=Role.agent,
            parts=[Part(root=TextPart(
                text="It is sunny and 72°F in Tokyo."))],
            task_id=context.task_id,
            context_id=context.context_id,
        )
    )

La risposta dell'utente viene inviata di nuovo all'agente come richiesta message/send con lo stesso taskId.

Agenti A2A (creati con ADK)

Se l'agente è creato con Agent Development Kit (ADK) ed esposto tramite A2A (utilizzando to_a2a()), racchiudi la funzione di domanda in LongRunningFunctionTool:

from google.adk.agents import Agent
from google.adk.tools.long_running_tool import LongRunningFunctionTool
from google.adk.a2a.utils.agent_to_a2a import to_a2a

def get_weather(city: str) -> str:
    """Returns weather information for a city."""
    return f"It is sunny and 72°F in {city}."

def ask_clarifying_question(question: str) -> None:
    """Asks the user a question and waits for their reply."""
    return None

root_agent = Agent(
    model="gemini-2.5-flash",
    name="weather_agent",
    instruction=(
        "If the user asks for weather without specifying a city, call "
        "`ask_clarifying_question` and wait. Do not guess."
    ),
    tools=[get_weather, LongRunningFunctionTool(ask_clarifying_question)],
)

a2a_app = to_a2a(root_agent, port=8000)

Agenti ADK su motore agente

Per gli agenti ADK ospitati dal motore di ragionamento su motore agente, emetti un evento RequestInput all'interno di uno strumento generatore o di un passaggio dell'agente personalizzato:

from google.adk.events import RequestInput

# Inside a generator tool or custom agent step
def ask_for_details():
    """Requests user input during tool or step execution."""
    yield RequestInput(
        interrupt_id="weather_city",
        message="Which city would you like the weather for?",
    )

Passaggi successivi