Instrucciones del sistema e ingeniería de instrucciones para la IA agéntica

Para compilar agentes de IA autónomos que funcionen de forma confiable y segura en producción en Google Cloud, puedes combinar instrucciones del sistema estructuradas, esquemas de herramientas explícitos, límites de razonamiento, controles de seguridad con intervención humana (HITL) y limpieza del contexto. A diferencia de los chatbots interactivos que dependen de instrucciones básicas de entrada y salida, los sistemas de agentes con Gemini realizan una planificación de varios pasos, invocan APIs externas, supervisan los comentarios de ejecución y mantienen la memoria de trabajo en flujos de trabajo de varios turnos.

En este documento, se describen los patrones de arquitectura y las prácticas de ingeniería de instrucciones para diseñar agentes autónomos. Si buscas sugerencias para escribir instrucciones interactivas para Gemini Cloud Assist o el chat del IDE, consulta Escribe mejores instrucciones para Gemini en Google Cloud.

Instrucciones del sistema

En las arquitecturas de agentes, usas instrucciones del sistema para definir la identidad, las reglas y los permisos de referencia del agente. A diferencia de las instrucciones de usuario estándar que cambian con cada turno, las instrucciones del sistema se definen una vez y se pasan de manera coherente en todos los turnos de ejecución.

Las instrucciones del sistema definen lo siguiente:

  • Identidad y rol de referencia: Define el rol y la función principal del agente, por ejemplo, "Eres un agente administrador de bases de datos".
  • Reglas de comportamiento: Establece restricciones operativas, límites de seguridad y requisitos de formato de salida, por ejemplo, "Nunca realices una operación de escritura sin aprobación humana" o "Devuelve los resultados como JSON".
  • Lineamientos para las llamadas a herramientas: Define las reglas de selección, orden y reintento de las herramientas.

En el ejemplo de la siguiente sección, se agrupa cada uno de estos elementos en su propia etiqueta XML: <role>, <rules> y <tool_usage>.

Las instrucciones del sistema no deben contener entradas dinámicas del entorno de ejecución, como preguntas de los usuarios, contenido de archivos o registros de ejecución de herramientas. Mantén estos valores dinámicos en las cargas útiles de contenido que se envían durante los turnos de ejecución.

Estructura las instrucciones del sistema con etiquetas XML

Dar formato a las instrucciones del sistema con una estructura XML ayuda al modelo a segmentar con precisión los diferentes tipos de orientación.

Las etiquetas XML no son una función codificada de forma rígida de la API de Gemini. En cambio, son una convención de ingeniería de instrucciones. Debido a que los modelos de Gemini se entrenan con código estructurado y páginas web, analizan las etiquetas XML para separar los tipos de instrucciones y evitar que se desvíen en las sesiones de varios turnos.

Cuando pases tu instrucción del sistema al SDK o a la API, no encierres todo el bloque de instrucciones en una etiqueta externa, como <system_instruction>. La API ya procesa toda la cadena como una instrucción del sistema. En su lugar, usa etiquetas individuales dentro del bloque para agrupar las instrucciones:

<role>
  You are an autonomous Cloud Infrastructure Management Agent responsible
  for diagnosing and remediating GKE cluster issues.
</role>

<rules>
  - Always run diagnostic tools before proposing or applying remediation.
  - Never delete storage volumes, IAM bindings, or database
    instances without explicit human authorization.
  - Verify target cluster and namespace names from diagnostic output before
    proposing changes.
</rules>

<tool_usage>
  - Call `gke_get_cluster_status` to fetch node pool health.
  - Call `gke_inspect_logs` to retrieve pod error logs.
  - Use strict JSON schemas when supplying tool parameters.
</tool_usage>

Cuando separas las instrucciones con etiquetas XML, como <role>, <rules> y <tool_usage>, el modelo trata cada bloque como una categoría distinta de orientación.

Etiquetas XML comunes para las instrucciones del sistema

Si bien Gemini puede analizar cualquier etiqueta XML personalizada que se ajuste a tu dominio, usar un conjunto de etiquetas comunes ayuda a mantener las instrucciones coherentes y más fáciles de mantener en todos los agentes.

En la siguiente tabla, se enumeran las etiquetas de ejemplo que puedes usar para estructurar las instrucciones del sistema. Los nombres de las etiquetas son convenciones, por lo que puedes cambiarles el nombre para que se adapten a tu agente. Por ejemplo, la guía de instrucciones de CX Agent Studio usa <constraints> para el tipo de orientación que este documento coloca en <rules>.

Etiqueta Descripción
<role> Define la identidad principal, la personificación y la función principal del agente.
<rules> Enumera las restricciones, las reglas de formato y los límites de seguridad.
<tool_usage> Describe las políticas para elegir y llamar a las herramientas.
<example> Contiene un ejemplo de pocos intentos que muestra una entrada y un resultado esperados. Usa una etiqueta por ejemplo.

Para obtener más detalles y patrones de instrucciones, consulta los siguientes recursos:

Prácticas recomendadas para la definición de herramientas y funciones

En los sistemas de agentes, usas herramientas y llamadas a funciones para otorgarles a los agentes la capacidad de interactuar con las APIs, las bases de datos y los microservicios de Google Cloud . Debido a que el modelo solicita la ejecución de código del cliente haciendo coincidir los esquemas que defines, es fundamental proporcionar declaraciones de herramientas claras y sin ambigüedades para evitar errores de invocación.

Principios del diseño de esquemas

Sigue estos principios cuando definas esquemas de herramientas:

  • Usa tipos explícitos: Especifica tipos de datos precisos, como string, integer, boolean, array o object, para cada parámetro en los esquemas de OpenAPI o JSON.
  • Proporciona descripciones significativas: Explica los requisitos de formato, las restricciones y los rangos válidos para cada parámetro, en lugar de depender solo de los nombres de los campos.
  • Declara los campos obligatorios: Completa el array required en los esquemas JSON para que el modelo no pase null ni omita argumentos para los campos obligatorios.
  • Restringe los valores con enumeraciones: Usa valores enum para los campos con entradas válidas fijas, como nombres de entornos o niveles de gravedad de los registros.

Ejemplo de esquema de declaración de función

En el siguiente ejemplo, se define una declaración de función con un esquema JSON para una herramienta que reinicia una implementación de Google Kubernetes Engine (GKE):

{
  "name": "restart_gke_deployment",
  "description": "Performs a rolling restart of a GKE deployment.",
  "parameters": {
    "type": "object",
    "properties": {
      "cluster_id": {
        "type": "string",
        "description": "Fully qualified GKE cluster resource ID."
      },
      "namespace": {
        "type": "string",
        "description": "Kubernetes namespace containing the deployment."
      },
      "deployment_name": {
        "type": "string",
        "description": "The exact metadata name of the deployment."
      },
      "environment": {
        "type": "string",
        "description": "Target environment for the restart.",
        "enum": ["dev", "staging", "prod"]
      },
      "reason": {
        "type": "string",
        "description": "Brief operational rationale for the restart."
      }
    },
    "required": ["cluster_id", "namespace", "deployment_name", "reason"]
  }
}

Control del presupuesto de razonamiento y pensamiento

Para realizar un razonamiento interno antes de tomar medidas en flujos de trabajo complejos, los agentes usan las capacidades de pensamiento de Gemini con el parámetro thinking_config. Este parámetro de configuración permite que los agentes realicen bucles de planificación, verificación y ejecución para validar las acciones antes de invocar las herramientas.

Implementa bucles de planificación, verificación y ejecución

Un bucle de planificación, verificación y ejecución consta de las siguientes etapas:

  1. Planificar: Analiza la instrucción, identifica las dependencias y formula una secuencia de llamadas a la herramienta.
  2. Verificar: Comprueba las llamadas a la herramienta propuestas con las restricciones del sistema, las políticas de seguridad y los parámetros obligatorios.
  3. Ejecución: Emite llamadas a herramientas y observa los comentarios de ejecución.

El pensamiento integrado se ejecuta en un canal interno en lugar de emitir etiquetas XML <thinking> en el texto de respuesta. Si configuras include_thoughts=True en thinking_config, puedes inspeccionar los resúmenes de pensamientos (part.thought) antes de una llamada a la herramienta:

1. User requests scaling down node pool 'pool-1' in cluster
   'prod-us-central1'.
2. Verification: Scaling down production node pools requires checking
   current CPU utilization first.
3. Plan: Call `get_node_pool_metrics` first. If utilization < 30%, request
   human approval before scaling down.

Cuando configures thinking_config en el SDK, establece thinking_level (para los modelos de Gemini 3) o thinking_budget (para los modelos de Gemini 2.5) para equilibrar la profundidad del razonamiento y la latencia.

Higiene de la ventana de contexto y memoria de trabajo

Si bien los modelos de Gemini insignia admiten una ventana de contexto de 1 millón de tokens, las secuencias de contexto largas pueden generar ruido, latencia y degradación del contexto. Mantener la higiene de la memoria de trabajo ayuda a garantizar que los agentes de larga duración sigan siendo precisos.

Estrategias para la higiene del contexto

Usa las siguientes estrategias para administrar el contexto en agentes de larga duración:

  • Delegación de subagentes: Delega subtareas aisladas, como el análisis de código o la búsqueda de registros, a subagentes de corta duración y devuelve solo resúmenes sintetizados al contexto principal.
  • Resumen de estado: Resume periódicamente el historial de varios turnos, descarta los registros de depuración transitorios y conserva los hechos clave.
  • Archivos de memoria: Conserva el estado estructurado, las restricciones del proyecto y el contexto operativo en archivos Markdown externos, como GOALS.md y MEMORY.md, en lugar de mantener historiales de conversaciones sin procesar completos en el contexto.

Puntos de control con interacción humana (HITL)

Los agentes autónomos que operan en entornos de Google Cloud en vivo deben aplicar puntos de control de aprobación para las operaciones de alto riesgo.

Operaciones de alto riesgo que requieren HITL

Exigir la aprobación humana antes de que un agente realice cualquiera de las siguientes operaciones:

  • Acceso y permisos: Modificar roles de Identity and Access Management (IAM), otorgar acceso a cuentas de servicio o hacer que los recursos sean de acceso público, por ejemplo, permitir el acceso no autenticado a un servicio o abrir reglas de firewall a todas las direcciones IP.
  • Borrado de recursos: Borrar recursos, como bases de datos de Cloud SQL, buckets de Cloud Storage, temas de Pub/Sub o grupos de nodos de GKE.
  • Facturación y cuota: Aprovisionar tipos de máquinas de alto costo, como pods de Cloud TPU o instancias de varias GPU, o aumentar los límites de cuota.

Pausas de aprobación de diseño

No dependas solo de las instrucciones de la instrucción para bloquear acciones destructivas. Debido a que el código de tu aplicación ejecuta herramientas, aplica verificaciones de aprobación de forma determinista en tu organizador interceptando las solicitudes de function_call de alto riesgo antes de ejecutarlas y presentando una carga útil de confirmación a un revisor humano:

{
  "action": "delete_cloud_sql_instance",
  "target_resource": "projects/my-prod/instances/user-db-primary",
  "risk_level": "CRITICAL",
  "status": "WAITING_FOR_HUMAN_APPROVAL"
}

Recuperación automática de errores y bucles de reintento

Los errores de ejecución de herramientas son inevitables en los entornos de Distributed Cloud. Los agentes deben controlar los errores transitorios, los códigos de estado PERMISSION_DENIED y las fallas de validación de esquemas de forma autónoma.

Arquitectura de comentarios de error

Cuando una llamada a la herramienta devuelva un error, vuelve a ingresar el resultado del error sin procesar en el contexto del agente junto con una guía para reintentar, en lugar de fallar de inmediato:

  • No coinciden los esquemas: Si el formato de un parámetro no es válido, devuelve el error de esquema al modelo para que pueda corregir los argumentos de la herramienta.
  • Errores de permiso denegado: Indica al agente que verifique los permisos de IAM necesarios o que recurra a herramientas de diagnóstico de solo lectura.
  • Límites de frecuencia y regulación: Controla los errores 429 transitorios con retirada exponencial en el código de cliente y devuelve errores de cuota persistentes al modelo para que pueda ajustar su plan.

Cuando uses la llamada a funciones, devuelve detalles de error estructurados en una parte de FunctionResponse (conservando el contenido y las firmas de pensamiento del turno anterior del modelo) en lugar de texto sin procesar:

from google.genai import types

error_part = types.Part.from_function_response(
    name="gke_get_cluster_status",
    response={
        "status": "ERROR",
        "error_code": "PERMISSION_DENIED",
        "message": (
            "Caller lacks permission 'container.clusters.get' on"
            " 'projects/demo/locations/us-central1/clusters/dev'."
        ),
        "remediation_hint": (
            "Verify service account permissions or check another project."
        ),
    },
)

Ejemplo de esquema de código antes y después

En la siguiente comparación, se ilustra el cambio de una instrucción de texto no estructurada heredada a una instrucción del sistema de agentes con esquemas de herramientas JSON estructurados con el SDK de IA generativa de Google.

Instrucción de texto no estructurado heredada

En el siguiente ejemplo, se incorpora un comando de shell dentro de una instrucción de texto no estructurada, lo que puede causar llamadas a la herramienta con alucinaciones o parámetros faltantes:

# Legacy unstructured approach (prone to hallucinated tool calls and missing
# parameters)
prompt = """
You are a Cloud helper. Restart the app deployment in namespace 'prod' for
cluster 'prod-cluster'.
Run command: kubectl rollout restart deployment/web-app -n prod
"""
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
)

Esquema de definición de herramientas y de instrucciones del sistema de agentes

En el siguiente ejemplo, se separa la instrucción del sistema de la instrucción del usuario y se declara un esquema de función explícito:

from google import genai
from google.genai import types

# 1. Define explicit function schema with required parameters
restart_deployment_tool = types.FunctionDeclaration(
    name="restart_gke_deployment",
    description=(
        "Executes a rolling restart for a Kubernetes deployment in Google"
        " Kubernetes Engine."
    ),
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "cluster_id": types.Schema(
                type=types.Type.STRING,
                description=(
                    "Fully qualified GKE cluster ID (e.g."
                    " projects/my-project/locations/us-central1/"
                    "clusters/prod-cluster)."
                ),
            ),
            "namespace": types.Schema(
                type=types.Type.STRING,
                description=(
                    "Kubernetes namespace (e.g. default, production)."
                ),
            ),
            "deployment_name": types.Schema(
                type=types.Type.STRING,
                description="Metadata name of the target deployment.",
            ),
        },
        required=["cluster_id", "namespace", "deployment_name"],
    ),
)

# 2. Configure System Instruction with identity, safety rules, and tools
system_instruction = """
<role>You are an autonomous Cloud Infrastructure Remediation Agent.</role>
<rules>
- Always validate parameter schemas before invoking tool calls.
- Require human approval before performing destructive actions.
- Verify cluster and namespace identifiers before invoking remediation tools.
</rules>
"""

config = types.GenerateContentConfig(
    system_instruction=system_instruction,
    tools=[types.Tool(function_declarations=[restart_deployment_tool])],
    thinking_config=types.ThinkingConfig(thinking_budget=1024),
)

client = genai.Client(vertexai=True, project="my-project", location="global")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=(
        "Restart the deployment 'web-app' in namespace 'prod' under"
        " cluster"
        " 'projects/my-proj/locations/us-central1/clusters/prod-cluster'."
    ),
    config=config,
)

# Inspect response.function_calls, validate arguments, and require human
# approval in your orchestrator before executing restart_gke_deployment.

¿Qué sigue?