Cómo agregar un paso de agente existente

Puedes agregar agentes de IA existentes como pasos en tu flujo de trabajo para transferir tareas a agentes especializados. Esto te permite componer flujos de trabajo de varios agentes que se coordinan entre diferentes agentes, cada uno de los cuales controla una parte específica de un proceso más grande.

Antes de comenzar

Antes de usar esta función, completa los siguientes pasos:

  • Asegúrate de que un administrador de Gemini Enterprise haya habilitado el botón de activación de la función Workflow Builder en la configuración de administración de funciones de tu app. Para obtener más información, consulta Administra las funciones de la app web.

  • Asegúrate de que los agentes que quieres agregar estén disponibles en tu organización. Esta función admite la incorporación de los siguientes agentes:

Agrega un paso de agente existente

App

  1. Abre la app web de Gemini Enterprise en un navegador.
  2. Navega a un agente existente o crea uno nuevo.
  3. En el creador de flujos, haz clic en Agregar paso.
  4. En el panel Agregar paso, haz clic en Agentes existentes para expandir la sección.

  5. Explora la lista de agentes disponibles.

  6. Haz clic en el agente que quieres agregar.

    El sistema agrega el paso del agente existente a tu flujo de trabajo. El agente seleccionado se ejecuta como parte de tu flujo de trabajo, recibe entradas de pasos anteriores y pasa salidas a pasos posteriores.

  7. En el lienzo, haz clic en el paso del agente existente para abrir su panel de configuración y establece lo siguiente:

    • Instrucción: Ingresa la instrucción o las instrucciones que se usan para activar el agente. Puedes incluir texto estático o resultados de referencia de pasos anteriores (por ejemplo, ${step_name.output}).

El paso del agente es una referencia dinámica al agente seleccionado. Si se actualiza el agente de origen o se publica una versión nueva, tu flujo de trabajo usará automáticamente la versión más reciente.

Para obtener más información sobre las limitaciones de esta función, consulta Problemas y limitaciones conocidos.

Cómo funcionan las preguntas de aclaración

Cuando un agente existente se ejecuta en un flujo de trabajo, puede pausar la ejecución para hacerle al usuario una pregunta aclaratoria si necesita información faltante para completar su tarea. Las preguntas aclaratorias se admiten de forma nativa cuando el agente al que se hace referencia emite una señal input-required (A2A) o un evento RequestInput (ADK).

Cuando se ejecuta un paso de agente existente y se requiere información adicional, ocurre lo siguiente:

  1. Pausas de ejecución: El flujo de trabajo pausa la ejecución en el paso del agente existente y, luego, inicia una instrucción con intervención humana (HITL).
  2. El usuario responde la instrucción: La app web de Gemini Enterprise muestra la pregunta aclaratoria del agente al usuario junto con un campo de texto para ingresar su respuesta.
  3. Se reanuda la ejecución: Cuando el usuario envía su respuesta, el flujo de trabajo reanuda el agente existente y le pasa la respuesta del usuario.
  4. Asistencia de varios turnos: El agente puede hacer varias preguntas aclaratorias de forma sucesiva en varios turnos hasta que recopile toda la información necesaria y produzca su resultado final.

Aislamiento de contexto

Durante un intercambio de preguntas aclaratorias, el agente de referencia solo recibe su propio historial de interacciones con el usuario y la instrucción inicial configurada para el nodo. Los resultados y las variables de otros pasos del flujo de trabajo no se pasan automáticamente al agente al que se hace referencia, a menos que se haga referencia explícita en la instrucción del paso.

Implementa preguntas aclaratorias en tu agente

Para admitir preguntas aclaratorias, configura tu agente personalizado para que emita una señal de entrada de solicitud a nivel de protocolo cuando necesite información adicional.

Agentes A2A (nativos)

Para los agentes que implementan el protocolo Agent-to-Agent (A2A) directamente, devuelve la tarea en el estado input-required con TaskUpdater, proporcionando la pregunta aclaratoria en la carga útil del mensaje:

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 respuesta del usuario se envía de vuelta a tu agente como una solicitud message/send con el mismo taskId.

Agentes A2A (creados con el ADK)

Si tu agente se compila con el Kit de desarrollo de agentes (ADK) y se expone a través de A2A (con to_a2a()), une tu función de preguntas en 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 del ADK en Agent Engine

Para los agentes del ADK alojados en el motor de razonamiento en Agent Engine, emite un evento RequestInput dentro de una herramienta de generador o un paso 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?",
    )

¿Qué sigue?