내보내기 형식 참조

이 문서에서는 에이전트 애플리케이션 내보내기 및 가져오기 파일의 디렉터리 구조와 파일 구성을 간략하게 설명합니다.

형식은 압축을 풀면 에이전트 애플리케이션 이름에 해당하는 루트 디렉터리 가 포함된 ZIP 파일입니다.

이 문서에 설명된 모든 경로는 루트 디렉터리를 기준으로 합니다. 다른 객체 (에이전트, 도구 등)에 대한 모든 참조는 displayName 값을 사용해야 합니다.

다음 도구 이름은 예약되어 있습니다.

• end_session
• transfer_to_agent
• customize_response

가져오기 및 내보내기를 할 때 개별 파일에 JSON 또는 YAML을 사용할 수 있습니다. 이 문서에 설명된 파일은 YAML을 사용하지만 JSON 구성원은 유사합니다.

루트 디렉터리

루트 디렉터리에는 애플리케이션의 기본 구성 파일이 포함되어 있습니다.

• app.yaml: 에이전트 애플리케이션의 중앙 구성 파일입니다. 다음과 같이 정의합니다.
  • displayName (문자열): 사람이 읽을 수 있는 애플리케이션 이름입니다.
  • rootAgent (문자열): 대화를 시작하는 에이전트의 표시 이름 입니다. 파일 이름 또는 디렉터리 이름을 사용하지 마세요.
  • audioProcessingConfig (객체): 텍스트 음성 변환 및 음성 텍스트 변환 설정입니다.
    • synthesizeSpeechConfigs (맵): 키는 언어 코드 (예: en-US)이고 값은 voice (문자열)가 포함된 객체입니다.
    • inactivityTimeout (문자열): 기간 문자열 (예: '2초')입니다.
    • ambientSoundConfig (객체): volumeGainDb (부동 소수점 수) 및 prebuiltAmbientSound (문자열)를 포함하여 배경 소음을 구성합니다.
  • loggingSettings (객체): 로그 및 녹화 구성입니다.
    • redactionConfig (객체): 민감한 정보 수정 구성입니다.
    • audioRecordingConfig (객체): gcsBucket (문자열)을 포함합니다.
    • bigqueryExportSettings (객체): enabled (불리언), project (문자열), dataset (문자열)을 포함합니다.
    • cloudLoggingSettings (객체): enableCloudLogging (불리언)을 포함합니다.
  • guardrails (문자열 목록): 전역적으로 적용되는 가드레일 이름 목록입니다.
  • variableDeclarations (객체 목록): 전역 변수의 스키마 정의입니다. 각 객체에는 다음이 포함됩니다.
    • name (문자열): 변수 이름입니다.
    • description (문자열): 변수의 목적에 대한 설명입니다.
    • schema (객체): 유형 정의 (예: { type: STRING } 또는 중첩된 속성)입니다.
    • default (모든 유형): 변수의 기본값입니다.
  • globalInstruction (문자열): 전역 시스템 안내 파일의 경로입니다.
  • languageSettings (객체):
    • defaultLanguageCode (문자열): 예: 'en-US'
    • supportedLanguageCodes (문자열 목록): 예: ["fr", "es"].
    • enableMultilingualSupport (불리언)
• environment.json: 환경별 변수의 키-값 쌍입니다.
• global_instruction.txt: 기본 프롬프트/안내가 포함된 텍스트 파일입니다.

agents/

이 디렉터리에는 애플리케이션의 모든 에이전트에 대한 정의가 포함되어 있습니다.

에이전트 구조 (agents/<agent_name>/)

• <agent_name>.yaml: 특정 에이전트의 구성 파일입니다.
  • displayName (문자열): 에이전트의 이름입니다.
  • modelSettings (객체): model (문자열)을 포함합니다.
  • instruction (문자열): 루트를 기준으로 안내 파일의 경로입니다 (예: agents/<agent_name>/instruction.txt).
  • tools (문자열 목록): 이 에이전트에서 사용할 수 있는 로컬 도구의 표시 이름입니다.
  • toolsets (객체 목록): 이 에이전트에서 사용할 수 있는 OpenAPI 도구 모음입니다. 각 객체에는 다음이 포함됩니다.
    • toolset (문자열): 도구 모음의 이름입니다.
    • toolIds (문자열 목록): 해당 도구 모음에서 노출할 특정 작업 ID입니다.
  • childAgents (문자열 목록): 이 에이전트가 전환할 수 있는 다른 에이전트의 표시 이름입니다. 이 관계는 단방향 (상위에서 하위로)입니다. 순환 전환이 명시적으로 의도되지 않는 한 하위 에이전트는 상위 에이전트를 하위 에이전트로 나열해서는 안 됩니다. 에이전트는 둘 이상의 상위 에이전트를 가질 수 없습니다(예외: 에스컬레이션 또는 만족도와 같은 공유 유틸리티 에이전트). 루트 에이전트는 다른 에이전트의 하위 에이전트로 나열될 수 없습니다.
  • *Callbacks (객체 목록): beforeModelCallbacks, afterModelCallbacks 등에 사용됩니다. 각 객체에는 다음이 포함됩니다.
    • pythonCode (문자열): 콜백 스크립트의 경로입니다.
    • disabled (불리언): 콜백이 활성 상태인지 여부입니다.
    • description (문자열): 콜백 로직에 대한 설명입니다.
• instruction.txt: 이 에이전트의 특정 시스템 프롬프트입니다. 도구에 대한 참조는 {@TOOL: <tool_display_name>} 문법을 사용해야 하고, 다른 에이전트에 대한 참조는 {@AGENT: <agent_display_name>}을 사용해야 하며, 변수는 {variable_name} (예: {firstname})을 사용하여 액세스해야 합니다.
• before_model_callbacks/등: 콜백 스크립트의 디렉터리입니다.

tools/

이 디렉터리에는 Python 함수 또는 데이터 저장소 검색기일 수 있는 '로컬' 도구가 포함되어 있습니다.

도구 구조 (tools/<tool_name>/)

• <tool_name>.yaml: 도구의 구성입니다. pythonFunction 또는 dataStoreTool 중 하나만 사용합니다. 둘 다 사용할 수 없습니다.
  • displayName (문자열): 도구의 이름입니다.
  • 옵션 A: Python 함수 도구
    • pythonFunction (객체):
      • name (문자열): 함수 이름입니다.
      • pythonCode (문자열): 루트를 기준으로 Python 구현의 경로입니다 (예: tools/<tool_name>/python_function/python_code.py).
      • description (문자열): LLM의 시맨틱 설명입니다.
  • 옵션 B: 데이터 저장소 도구
    • dataStoreTool (객체):
      • name (문자열): 도구 이름입니다 (일반적으로 디렉터리 이름과 일치).
      • description (문자열): 에이전트의 도구 목적에 대한 설명입니다.
      • engineSource (객체):
        • dataStoreSources (객체 목록):
          • dataStore (객체):
            • name (문자열): 데이터 저장소의 전체 리소스 이름(예: projects/...) 또는 환경 변수(예: $env_var)입니다.
      • modalityConfigs (객체 목록): 선택사항입니다. 텍스트 또는 오디오의 동작을 구성합니다.
        • modalityType (열거형): TEXT 또는 AUDIO입니다.
        • groundingConfig (객체):
          • groundingLevel (부동 소수점 수): 예: 4.0
  • executionType (열거형): 예: SYNCHRONOUS
• python_function/python_code.py: Python 코드 파일 (Python 함수 도구에만 해당).

toolsets/

이 디렉터리에는 OpenAPI 기반 도구 모음이 포함되어 있습니다.

도구 모음 구조 (toolsets/<toolset_name>/)

• <toolset_name>.yaml: 도구 모음의 구성입니다.
  • displayName (문자열): 도구 모음의 이름입니다.
  • openApiToolset (객체):
    • openApiSchema (문자열): 루트를 기준으로 OpenAPI 스키마 파일의 경로입니다. (예: toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
    • apiAuthentication (객체): 인증 구성 (예: serviceAgentIdTokenAuthConfig)입니다.
• open_api_toolset/open_api_schema.yaml: OpenAPI 사양 파일입니다.

guardrails/

이 디렉터리는 콘텐츠 안전 필터를 정의합니다.

가드레일 구조 (guardrails/<guardrail_name>/)

• <guardrail_name>.yaml:
  • displayName (문자열): 가드레일의 이름입니다.
  • description (문자열): 목적입니다.
  • enabled (불리언): 활성 상태인지 여부입니다.
  • contentFilter (객체):
    • bannedContentsInUserInput (문자열 목록): 차단할 단어와 구문입니다.
    • matchType (문자열): 예: 'WORD_BOUNDARY_STRING_MATCH'
  • action (객체):
    • respondImmediately (객체):
      • responses (객체 목록): 각 객체에는 text (문자열)가 포함됩니다.

examples/

이 디렉터리에는 에이전트 애플리케이션에서 사용되는 퓨샷 예시의 정의가 포함되어 있습니다.

예시 구조 (examples/<example_name>/)

• <example_name>.yaml: 예시의 구성입니다.

evaluations/

이 디렉터리에는 테스트 정의가 포함되어 있습니다.

평가 구조 (evaluations/<evaluation_name>/)

• <evaluation_name>.yaml: 예상 입력/출력으로 테스트 시나리오를 정의합니다.

evaluationDatasets/

이 디렉터리에는 평가 데이터 세트가 포함되어 있습니다.

평가 데이터 세트 구조 (evaluationDatasets/<evaluation_dataset_name>/)

• <evaluation_dataset_name>.yaml: 평가 데이터 세트의 구성입니다.