에이전트형 AI를 위한 시스템 안내 및 프롬프트 엔지니어링

Google Cloud에서 프로덕션 환경에서 안정적이고 안전하게 작동하는 자율형 AI 에이전트를 빌드하려면 구조화된 시스템 안내, 명시적 도구 스키마, 추론 경계, 휴먼인더루프 안전 제어, 컨텍스트 위생을 결합하면 됩니다. 기본적인 입력-출력 프롬프팅에 의존하는 대화형 챗봇과 달리 Gemini를 사용하는 에이전트 시스템은 멀티턴 워크플로 전반에서 다단계 계획을 수행하고, 외부 API를 호출하고, 실행 피드백을 모니터링하고, 작업 메모리를 유지합니다.

이 문서에서는 자율 에이전트를 설계하기 위한 아키텍처 패턴과 프롬프트 엔지니어링 관행을 설명합니다. Gemini Cloud Assist 또는 IDE 채팅을 위한 대화형 프롬프트 작성에 관한 팁을 찾고 있다면 Google Cloud의 Gemini에 보다 효과적인 프롬프트 작성을 참조하세요.

시스템 안내

에이전트 아키텍처에서는 시스템 안내를 사용하여 에이전트의 기본 ID, 규칙, 권한을 정의합니다. 각 차례마다 변경되는 표준 사용자 프롬프트와 달리 시스템 안내를 한 번 정의하고 실행 차례마다 일관되게 전달합니다.

시스템 요청 사항은 다음을 정의합니다.

• 기준 ID 및 역할: 에이전트의 페르소나와 기본 기능을 정의합니다(예: '데이터베이스 관리자 에이전트').
• 동작 규칙: 운영 제약 조건, 안전 경계, 출력 형식 요구사항을 설정합니다(예: '사람의 승인 없이 쓰기 작업을 수행하지 않음' 또는 '결과를 JSON으로 반환').
• 도구 호출 가이드라인: 도구 선택, 순서 지정, 재시도 규칙을 정의합니다.

다음 섹션의 예에서는 이러한 각 항목을 자체 XML 태그인 <role>, <rules>, <tool_usage>로 그룹화합니다.

시스템 안내에는 사용자 질문, 파일 콘텐츠, 도구 실행 로그와 같은 동적 런타임 입력이 포함되어서는 안 됩니다. 실행 차례 중에 전송되는 콘텐츠 페이로드에 이러한 동적 값을 유지합니다.

XML 태그를 사용하여 시스템 요청 사항 구조화

XML 구조를 사용하여 시스템 안내를 형식 지정하면 모델이 다양한 유형의 안내를 정확하게 세분화하는 데 도움이 됩니다.

XML 태그는 Gemini API의 하드코딩된 기능이 아닙니다. 대신 프롬프트 엔지니어링 규칙입니다. Gemini 모델은 구조화된 코드와 웹페이지를 기반으로 학습되므로 XML 태그를 파싱하여 요청 사항 유형을 구분하고 멀티턴 세션에서 요청 사항 드리프트를 방지합니다.

SDK 또는 API에 시스템 요청 사항을 전달할 때 전체 요청 사항 블록을 <system_instruction>와 같은 외부 태그로 래핑하지 마세요. API는 이미 전체 문자열을 시스템 안내로 처리합니다. 대신 블록 내에서 개별 태그를 사용하여 명령어를 그룹화합니다.

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

<role>, <rules>, <tool_usage>과 같은 XML 태그로 요청 사항을 구분하면 모델은 각 블록을 별도의 안내 카테고리로 취급합니다.

시스템 요청 사항에 사용되는 일반적인 XML 태그

Gemini는 도메인에 맞는 모든 커스텀 XML 태그를 파싱할 수 있지만, 공통 태그 집합을 사용하면 요청 사항을 일관되게 유지하고 에이전트 간에 더 쉽게 유지보수할 수 있습니다.

다음 표에는 시스템 안내를 구성하는 데 사용할 수 있는 태그 예시가 나와 있습니다. 태그 이름은 규칙이므로 에이전트에 맞게 이름을 바꿀 수 있습니다. 예를 들어 CX Agent Studio 요청 사항 가이드는 이 문서에서 <rules>에 배치하는 안내 유형에 <constraints>를 사용합니다.

태그	설명
<role>	에이전트의 핵심 정체성, 페르소나, 주요 기능을 정의합니다.
<rules>	제약 조건, 서식 규칙, 안전 경계를 나열합니다.
<tool_usage>	도구 선택 및 호출에 관한 정책을 설명합니다.
<example>	예상 입력 및 출력을 보여주는 퓨샷 예시를 포함합니다. 예시당 하나의 태그를 사용합니다.

자세한 내용과 프롬프트 패턴은 다음 리소스를 참고하세요.

• 시스템 안내
• 시스템 안내 사용
• 구조 프롬프트
• Gemini 3 시작하기

도구 및 함수 정의 권장사항

에이전트 시스템에서는 도구 및 함수 호출을 사용하여 에이전트가 Google Cloud API, 데이터베이스, 마이크로서비스와 상호작용할 수 있는 기능을 부여합니다. 모델은 정의된 스키마를 일치시켜 클라이언트 측 코드 실행을 요청하므로 호출 오류를 방지하려면 명확하고 모호하지 않은 도구 선언을 제공하는 것이 중요합니다.

스키마 설계 원칙

도구 스키마를 정의할 때는 다음 원칙을 따르세요.

• 명시적 입력 사용: OpenAPI 또는 JSON 스키마의 모든 매개변수에 대해 string, integer, boolean, array, object와 같은 정확한 데이터 유형을 지정합니다.
• 의미 있는 설명 제공: 필드 이름에만 의존하지 말고 각 매개변수의 형식 요구사항, 제약 조건, 유효한 범위를 설명합니다.
• 필수 필드 선언: 모델이 null를 전달하거나 필수 필드의 인수를 생략하지 않도록 JSON 스키마에서 required 배열을 채웁니다.
• enum으로 값 제한: 환경 이름이나 로그 심각도 수준과 같이 유효한 입력이 고정된 필드에는 enum 값을 사용합니다.

함수 선언 스키마 예시

다음 예시에서는 Google Kubernetes Engine(GKE) 배포를 다시 시작하는 도구의 JSON 스키마를 사용하여 함수 선언을 정의합니다.

{
  "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"]
  }
}

추론 및 사고 예산 관리

복잡한 워크플로에서 작업을 수행하기 전에 내부 추론을 수행하기 위해 에이전트는 thinking_config 파라미터와 함께 Gemini 사고 기능을 사용합니다. 이 구성을 사용하면 에이전트가 도구를 호출하기 전에 계획-검증-실행 루프를 수행하여 작업을 검증할 수 있습니다.

계획-검증-실행 루프 구현

계획-확인-실행 루프는 다음 단계로 구성됩니다.

1. 계획: 프롬프트를 분석하고, 종속 항목을 식별하고, 일련의 도구 호출을 작성합니다.
2. 확인: 제안된 도구 호출을 시스템 제약 조건, 안전 정책, 필수 파라미터와 비교하여 확인합니다.
3. 실행: 도구 호출을 실행하고 실행 피드백을 확인합니다.

기본 제공 사고는 대답 텍스트에서 <thinking> XML 태그를 내보내는 대신 내부 채널에서 실행됩니다. thinking_config에서 include_thoughts=True를 설정하면 도구 호출 전에 사고 요약(part.thought)을 검사할 수 있습니다.

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.

SDK에서 thinking_config를 구성할 때 thinking_level(Gemini 3 모델의 경우) 또는 thinking_budget(Gemini 2.5 모델의 경우)를 설정하여 추론 깊이와 지연 시간의 균형을 맞춥니다.

컨텍스트 윈도우 상태 관리 및 작업 메모리

주력 Gemini 모델은 100만 토큰 컨텍스트 윈도우를 지원하지만 긴 컨텍스트 시퀀스는 노이즈, 지연 시간, 컨텍스트 저하를 유발할 수 있습니다. 작업 메모리 위생을 유지하면 장기 실행 에이전트의 정확성을 유지할 수 있습니다.

컨텍스트 위생 전략

다음 전략을 사용하여 장기 실행 에이전트의 컨텍스트를 관리하세요.

• 하위 에이전트 위임: 코드 분석 또는 로그 검색과 같은 격리된 하위 작업을 단기 하위 에이전트에 위임하여 합성된 요약만 기본 컨텍스트에 반환합니다.
• 상태 요약: 멀티턴 기록을 주기적으로 요약하여 임시 디버그 로그를 삭제하고 주요 사실을 보존합니다.
• 메모리 파일: 전체 원시 대화 기록을 컨텍스트에 보관하는 대신 GOALS.md 및 MEMORY.md와 같은 외부 마크다운 파일에 구조화된 상태, 프로젝트 제약 조건, 운영 컨텍스트를 유지합니다.

인간 참여형(HITL) 체크포인트

실시간 Google Cloud 환경에서 작동하는 자율 에이전트는 위험도가 높은 작업에 대해 승인 체크포인트를 적용해야 합니다.

HITL이 필요한 고위험 작업

에이전트가 다음 작업을 수행하기 전에 사람의 승인이 필요합니다.

• 액세스 및 권한: Identity and Access Management(IAM) 역할 수정, 서비스 계정 액세스 권한 부여, 리소스 공개 액세스 허용(예: 서비스에 대한 인증되지 않은 액세스 허용 또는 모든 IP 주소에 대한 방화벽 규칙 열기)
• 리소스 삭제: Cloud SQL 데이터베이스, Cloud Storage 버킷, Pub/Sub 주제, GKE 노드 풀과 같은 리소스를 삭제합니다.
• 결제 및 할당량: Cloud TPU Pod 또는 멀티 GPU 인스턴스와 같은 고비용 머신 유형을 프로비저닝하거나 할당량 한도를 상향 조정합니다.

디자인 승인 일시중지

파괴적인 작업을 차단하기 위해 프롬프트 지침에만 의존하지 마세요. 애플리케이션 코드가 도구를 실행하므로 실행 전에 위험도가 높은 function_call 요청을 가로채고 검토자에게 확인 페이로드를 표시하여 조정자에서 승인 검사를 결정론적으로 적용합니다.

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

자동 오류 복구 및 재시도 루프

분산 클라우드 환경에서는 도구 실행 실패가 불가피합니다. 에이전트는 일시적인 오류, PERMISSION_DENIED 상태 코드, 스키마 검증 실패를 자율적으로 처리해야 합니다.

오류 피드백 아키텍처

도구 호출에서 오류가 반환되면 즉시 실패하는 대신 재시도 안내와 함께 원시 오류 출력을 에이전트의 컨텍스트에 다시 입력합니다.

• 스키마 불일치: 매개변수 형식이 잘못된 경우 모델에 스키마 오류를 반환하여 도구 인수를 수정할 수 있도록 합니다.
• 권한 거부 오류: 에이전트에게 필요한 IAM 권한을 확인하거나 읽기 전용 진단 도구로 대체하도록 지시합니다.
• 비율 제한 및 제한: 클라이언트 코드에서 지수 백오프를 사용하여 일시적인 429 오류를 처리하고, 모델이 계획을 조정할 수 있도록 영구 할당량 오류를 모델에 반환합니다.

함수 호출을 사용할 때는 원시 텍스트가 아닌 FunctionResponse 부분에 구조화된 오류 세부정보를 반환합니다(이전 모델 차례의 콘텐츠 및 사고 서명 유지).

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

코드 스키마 전후 예시

다음 비교는 Google 생성형 AI SDK를 사용하여 기존의 비정형 텍스트 프롬프트에서 구조화된 JSON 도구 스키마가 있는 에이전트형 시스템 안내로 전환하는 방법을 보여줍니다.

기존 비정형 텍스트 프롬프트

다음 예시에서는 비정형 텍스트 프롬프트 내에 셸 명령어를 삽입합니다. 이로 인해 할루시네이션 도구 호출 또는 누락된 매개변수가 발생할 수 있습니다.

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

에이전트형 시스템 요청 사항 및 도구 정의 스키마

다음 예시에서는 시스템 안내를 사용자 프롬프트와 분리하고 명시적 함수 스키마를 선언합니다.

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.

다음 단계

• Google Cloud 콘솔 또는 IDE 채팅에서 대화형 프롬프트를 작성하려면 Google Cloud의 Gemini에 대해 더 나은 프롬프트 작성을 참조하세요.
• Gemini 책임감 있는 AI 원칙에 대한 자세한 내용은 Gemini를 사용한Google Cloud 및 책임감 있는 AI를 참조하세요.
• 데이터 개인 정보 보호 및 거버넌스에 대한 자세한 내용은 Google Cloud 의 Gemini 제품에서 사용자 데이터를 사용하는 방법을 참조하세요.