Adicionar uma etapa de agente

Você pode adicionar agentes de IA atuais como etapas no fluxo de trabalho para transferir tarefas a agentes especializados. Isso permite criar fluxos de trabalho multiagentes que orquestram diferentes agentes, cada um deles processando uma parte específica de um processo maior.

Antes de começar

Antes de usar esse recurso, conclua as etapas a seguir:

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

  • Confirme se os agentes que você quer adicionar estão disponíveis na sua organização. Esse recurso oferece suporte à adição dos seguintes agentes:

Adicionar uma etapa de agente atual

App

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

  5. Navegue pela lista de agentes disponíveis.

  6. Clique no agente que você quer adicionar.

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

  7. No painel, clique na etapa de agente atual para abrir o painel de configuração e configure o seguinte:

    • Comando: insira o comando ou as instruções usadas para acionar o agente. Você pode 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, o 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 têm suporte nativo quando o agente referenciado emite um sinal input-required (A2A) ou um evento RequestInput (ADK).

Quando uma etapa de agente atual é executada e exige mais informações:

  1. A execução é pausada: o fluxo de trabalho pausa a execução na etapa de agente atual 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, juntamente com um campo de texto para inserir a resposta.
  3. A execução é retomada: quando o usuário envia a resposta, o fluxo de trabalho retoma o agente atual, transmitindo a resposta do usuário de volta ao agente.
  4. Suporte multiturno: o agente pode fazer várias perguntas de esclarecimento em sucessão em várias rodadas 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 só recebe o histórico de interação com o usuário e o comando inicial configurado para o nó. As saídas e variáveis de outras etapas no fluxo de trabalho não são transmitidas automaticamente ao agente referenciado, a menos que sejam referenciadas explicitamente no comando da etapa.

Implementar perguntas de esclarecimento no agente

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

Agentes do 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 do A2A (criados com o ADK)

Se o agente for criado com o Kit de Desenvolvimento de Agente (ADK) e exposto pelo A2A (usando to_a2a()), encapsule a função de perguntas 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 de gerador 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