Instruções do sistema e engenharia de comandos para IA agêntica

Para criar agentes de IA autônomos que operem de maneira confiável e segura em produção no Google Cloud, combine instruções de sistema estruturadas, esquemas de ferramentas explícitos, limites de raciocínio, controles de segurança human-in-the-loop (HITL) e higiene de contexto. Ao contrário dos chatbots interativos que dependem de comandos básicos de entrada e saída, os sistemas agênticos com o Gemini realizam planejamento em várias etapas, invocam APIs externas, monitoram o feedback de execução e mantêm a memória de trabalho em fluxos de trabalho de vários turnos.

Neste documento, descrevemos padrões arquitetônicos e práticas de engenharia de comandos para projetar agentes autônomos. Se você estiver procurando dicas sobre como escrever comandos interativos para o Gemini Cloud Assist ou o chat do ambiente de desenvolvimento integrado, consulte Escrever comandos melhores para o Gemini no Google Cloud.

Instruções do sistema

Em arquiteturas de agentes, você usa instruções do sistema para definir a identidade, as regras e as permissões de referência do agente. Ao contrário dos comandos de usuário padrão que mudam a cada turno, você define as instruções do sistema uma vez e as transmite de maneira consistente em todos os turnos de execução.

As instruções do sistema definem o seguinte:

  • Identidade e papel de referência: defina a persona e a função principal do agente. Por exemplo, "Você é um agente administrador de banco de dados".
  • Regras de comportamento: estabeleça restrições operacionais, limites de segurança e requisitos de formato de saída. Por exemplo, "Nunca execute uma operação de gravação sem aprovação humana" ou "Retorne os resultados como JSON".
  • Diretrizes de chamada de ferramentas: defina regras de seleção, ordenação e nova tentativa de ferramentas.

O exemplo na próxima seção agrupa cada um deles na própria tag XML: <role>, <rules> e <tool_usage>.

As instruções do sistema não podem conter entradas dinâmicas de ambiente de execução, como perguntas do usuário, conteúdo de arquivos ou registros de execução de ferramentas. Mantenha esses valores dinâmicos nos payloads de conteúdo enviados durante as rodadas de execução.

Estruturar instruções do sistema com tags XML

Formatar as instruções do sistema usando uma estrutura XML ajuda o modelo a segmentar com precisão diferentes tipos de orientação.

As tags XML não são um recurso fixado no código da API Gemini. Em vez disso, eles são uma convenção de engenharia de comandos. Como os modelos do Gemini são treinados em códigos estruturados e páginas da Web, eles analisam tags XML para separar tipos de instrução e evitar desvios de instrução em sessões de várias interações.

Ao transmitir a instrução do sistema para o SDK ou a API, não envolva todo o bloco de instruções em uma tag externa, como <system_instruction>. A API já processa toda a string como uma instrução do sistema. Em vez disso, use tags individuais dentro do bloco para agrupar instruções:

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

Quando você separa as instruções com tags XML, como <role>, <rules> e <tool_usage>, o modelo trata cada bloco como uma categoria distinta de orientação.

Tags XML comuns para instruções do sistema

Embora o Gemini possa analisar qualquer tag XML personalizada que se encaixe no seu domínio, usar um conjunto de tags comuns ajuda a manter as instruções consistentes e mais fáceis de manter em todos os agentes.

A tabela a seguir lista exemplos de tags que podem ser usadas para estruturar instruções do sistema. Os nomes de tags são convenções, então você pode renomeá-los para se adequar ao seu agente. Por exemplo, o guia de instruções do CX Agent Studio usa <constraints> para o tipo de orientação que este documento coloca em <rules>.

Tag Descrição
<role> Define a identidade, o perfil e a função principal do agente.
<rules> Lista restrições, regras de formatação e limites de segurança.
<tool_usage> Descreve as políticas para escolher e chamar ferramentas.
<example> Contém um exemplo de few-shot que mostra uma entrada e uma saída esperadas. Use uma tag por exemplo.

Para mais detalhes e padrões de comandos, consulte os seguintes recursos:

Práticas recomendadas para definição de ferramentas e funções

Em sistemas de agentes, você usa ferramentas e chamadas de função para permitir que os agentes interajam com APIs, bancos de dados e microsserviços do Google Cloud . Como o modelo solicita a execução do código do lado do cliente ao corresponder aos esquemas que você define, é fundamental fornecer declarações de ferramentas claras e inequívocas para evitar erros de invocação.

Princípios de design de esquema

Siga estes princípios ao definir esquemas de ferramentas:

  • Use a digitação explícita: especifique tipos de dados precisos, como string, integer, boolean, array ou object, para cada parâmetro em esquemas OpenAPI ou JSON.
  • Forneça descrições significativas: explique os requisitos de formato, as restrições e os intervalos válidos para cada parâmetro, em vez de confiar apenas nos nomes dos campos.
  • Declarar campos obrigatórios: preencha a matriz required em esquemas JSON para que o modelo não transmita null ou omita argumentos para campos obrigatórios.
  • Restringir valores com tipos enumerados: use valores enum para campos com entradas válidas fixas, como nomes de ambiente ou níveis de gravidade de registro.

Exemplo de esquema de declaração de função

O exemplo a seguir define uma declaração de função com um esquema JSON para uma ferramenta que reinicia uma implantação do 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"]
  }
}

Controle de raciocínio e orçamento de pensamento

Para realizar raciocínios internos antes de agir em fluxos de trabalho complexos, os agentes usam as capacidades de raciocínio do Gemini com o parâmetro thinking_config. Essa configuração permite que os agentes realizem loops de planejamento, verificação e execução para validar ações antes de invocar ferramentas.

Implementar loops de planejamento, verificação e execução

Um loop de planejamento, verificação e execução consiste nas seguintes etapas:

  1. Planejar: analisar o comando, identificar dependências e formular uma sequência de chamadas de ferramentas.
  2. Verificar: confira se as chamadas de ferramentas propostas estão de acordo com as restrições do sistema, as políticas de segurança e os parâmetros necessários.
  3. Executar: emitir chamadas de ferramenta e observar o feedback da execução.

O pensamento integrado é executado em um canal interno, em vez de emitir tags XML <thinking> no texto de resposta. Se você definir include_thoughts=True em thinking_config, poderá inspecionar os resumos de pensamento (part.thought) antes de uma chamada de ferramenta:

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.

Ao configurar thinking_config no SDK, defina thinking_level (para modelos do Gemini 3) ou thinking_budget (para modelos do Gemini 2.5) para equilibrar a profundidade do raciocínio e a latência.

Higiene da janela de contexto e memória de trabalho

Embora os principais modelos do Gemini ofereçam suporte a uma janela de contexto de 1 milhão de tokens, sequências de contexto longas podem introduzir ruído, latência e degradação de contexto. Manter a higiene da memória de trabalho ajuda a garantir que os agentes de longa duração permaneçam precisos.

Estratégias para higiene de contexto

Use as estratégias a seguir para gerenciar o contexto em agentes de longa duração:

  • Delegação de subagentes: delegue subtarefas isoladas, como análise de código ou pesquisa de registros, a subagentes de curta duração, retornando apenas resumos sintetizados ao contexto principal.
  • Resumo de estado: resuma periodicamente o histórico de várias interações, descartando registros de depuração temporários e preservando fatos importantes.
  • Arquivos de memória: Persista o estado estruturado, as restrições do projeto e o contexto operacional em arquivos Markdown externos, como GOALS.md e MEMORY.md, em vez de manter históricos de conversas brutos inteiros no contexto.

Pontos de verificação de human-in-the-loop (HITL)

Os agentes autônomos que operam em ambientes Google Cloud ativos precisam aplicar pontos de verificação de aprovação para operações de alto risco.

Operações de alto risco que exigem HITL

Exigir aprovação humana antes que um agente realize qualquer uma das seguintes operações:

  • Acesso e permissões: modificar papéis do Identity and Access Management (IAM), conceder acesso à conta de serviço ou tornar os recursos acessíveis publicamente, como permitir o acesso não autenticado a um serviço ou abrir regras de firewall para todos os endereços IP.
  • Exclusão de recursos: excluir recursos como bancos de dados do Cloud SQL, buckets do Cloud Storage, tópicos do Pub/Sub ou pools de nós do GKE.
  • Faturamento e cota: provisionamento de tipos de máquina de alto custo, como Pods do Cloud TPU ou instâncias com várias GPUs, ou aumento dos limites de cota.

Pausas para aprovação do design

Não dependa apenas das instruções do comando para bloquear ações destrutivas. Como o código do aplicativo executa ferramentas, aplique verificações de aprovação de forma determinística no orquestrador interceptando solicitações function_call de alto risco antes de executá-las e apresentando um payload de confirmação a um revisor humano:

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

Recuperação automática de erros e loops de repetição

Falhas na execução de ferramentas são inevitáveis em ambientes de nuvem distribuídos. Os agentes precisam lidar com erros temporários, códigos de status PERMISSION_DENIED e falhas de validação de esquema de forma autônoma.

Arquitetura de feedback de erros

Quando uma chamada de ferramenta retornar um erro, envie a saída de erro bruta de volta ao contexto do agente com orientações de nova tentativa, em vez de falhar imediatamente:

  • Incompatibilidades de esquema: se um formato de parâmetro for inválido, retorne o erro de esquema ao modelo para que ele possa corrigir os argumentos da ferramenta.
  • Erros de permissão negada: instrua o agente a verificar as permissões necessárias do IAM ou usar ferramentas de diagnóstico somente leitura.
  • Limites de taxa e limitação: processe erros temporários de 429 com espera exponencial no código do cliente e retorne erros de cota persistentes ao modelo para que ele possa ajustar o plano.

Ao usar a chamada de função, retorne detalhes de erro estruturados em uma parte FunctionResponse (preservando o conteúdo e as assinaturas de pensamento do turno anterior do modelo), em vez de texto bruto:

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."
        ),
    },
)

Exemplo de esquema de código antes e depois

A comparação a seguir ilustra a mudança de um comando de texto legado e não estruturado para uma instrução de sistema agêntica com esquemas de ferramentas JSON estruturados usando o SDK de IA generativa do Google.

Comando de texto não estruturado legado

O exemplo a seguir incorpora um comando shell em um comando de texto não estruturado, o que pode causar chamadas de ferramentas alucinadas ou parâmetros ausentes:

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

Instrução do sistema agêntico e esquema de definição de ferramentas

O exemplo a seguir separa a instrução do sistema do comando do usuário e declara um esquema de função 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.

A seguir