Adicionar uma etapa de agente

É possível adicionar agentes de IA como etapas no fluxo de trabalho para transferir tarefas para agentes especializados. Isso permite criar Agentic Workflows que orquestram diferentes agentes, cada um lidando com uma parte específica de um processo maior.

Antes de começar

Antes de usar esse recurso, siga estas etapas:

  • Verifique se um administrador do Gemini Enterprise ativou o recurso Workflow Builder nas configurações de gerenciamento de recursos do app. Para mais informações, consulte Gerenciar recursos do app da Web.

  • Verifique se os agentes que você quer adicionar estão disponíveis na sua organização. Esse recurso permite adicionar os seguintes agentes:

Adicionar uma etapa de agente atual

App

  1. Abra o app da Web do Gemini Enterprise em um navegador.
  2. Acesse um agente atual ou crie um novo.
  3. No criador de fluxos, clique em Adicionar etapa.
  4. No painel Adicionar etapa, clique em Agentes atuais para abrir a seção.

  5. Navegue pela lista de agentes disponíveis.

  6. Clique no agente que você quer adicionar.

    O sistema adiciona a etapa do agente ao seu fluxo de trabalho. O agente selecionado é executado como parte do fluxo de trabalho, recebendo entradas de etapas anteriores e transmitindo saídas para etapas posteriores.

  7. Na tela, clique na etapa do agente para abrir o painel de configuração e defina o seguinte:

    • Comando: insira o comando ou as instruções usadas para acionar o agente. É possível incluir texto estático ou saídas de referência de etapas anteriores (por exemplo, ${step_name.output}).

A etapa do agente é uma referência dinâmica ao agente selecionado. Se o agente de origem for atualizado ou uma nova versão for lançada, seu fluxo de trabalho usará automaticamente a versão mais recente.

Para mais informações sobre as limitações desse recurso, consulte Problemas e limitações conhecidos.

Como funcionam as perguntas de esclarecimento

Quando um agente atual é executado em um fluxo de trabalho, ele pode pausar a execução para fazer uma pergunta de esclarecimento ao usuário se precisar de informações ausentes para concluir a tarefa. As perguntas de esclarecimento são compatíveis de forma nativa quando o agente referenciado emite um sinal input-required (A2A) ou um evento RequestInput (ADK).

Quando uma etapa do agente é executada e requer mais informações:

  1. Pausas na execução: o fluxo de trabalho pausa a execução na etapa atual do agente e inicia um comando human-in-the-loop (HITL).
  2. O usuário responde ao comando: o app da Web do Gemini Enterprise mostra a pergunta de esclarecimento do agente ao usuário, junto com um campo de texto para inserir a resposta.
  3. Retomada da execução: quando o usuário envia a resposta, o fluxo de trabalho retoma o agente atual, transmitindo a resposta do usuário de volta para ele.
  4. Suporte a várias interações: o agente pode fazer várias perguntas de esclarecimento em sucessão em várias interações até coletar todas as informações necessárias e produzir a saída final.

Isolamento de contexto

Durante uma troca de perguntas de esclarecimento, o agente referenciado recebe apenas o próprio histórico de interações com o usuário e o comando inicial configurado para o nó. As saídas e variáveis de outras etapas do fluxo de trabalho não são transmitidas automaticamente para o agente referenciado, a menos que sejam explicitamente referenciadas no comando da etapa.

Implementar perguntas de esclarecimento no agente

Para dar suporte a perguntas de esclarecimento, configure seu agente personalizado para emitir um sinal de entrada de solicitação no nível do protocolo quando precisar de mais informações.

Agentes A2A (nativos)

Para agentes que implementam o protocolo Agent-to-Agent (A2A) diretamente, retorne a tarefa no estado input-required com TaskUpdater, fornecendo a pergunta de esclarecimento no payload da mensagem:

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,
        )
    )

A resposta do usuário é enviada de volta ao agente como uma solicitação message/send com o mesmo taskId.

Agentes A2A (criados com o ADK)

Se o agente for criado com o Kit de Desenvolvimento de Agente (ADK) e exposto por A2A (usando to_a2a()), envolva a função de pergunta em 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)

Agentes do ADK no Agent Engine

Para agentes do ADK hospedados no mecanismo de raciocínio no Agent Engine, emita um evento RequestInput em uma ferramenta geradora ou etapa de agente personalizado:

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?",
    )

A seguir