플레이북

플레이북은 생성형 에이전트의 기본 구성요소입니다. 생성형 에이전트에는 일반적으로 여러 플레이북이 있으며 각 플레이북은 특정 태스크를 처리하도록 정의됩니다. 플레이북 데이터는 LLM에 제공되므로, 질문에 답변하고 태스크를 수행하는 데 필요한 정보가 포함됩니다. 각 플레이북은 정보를 제공하거나, 외부 서비스에 쿼리를 전송하거나, 하위 태스크 처리를 위해 대화 처리를 흐름 또는 다른 플레이북으로 연기할 수 있습니다.

제한사항

다음과 같은 제한사항이 적용됩니다.

  • 플레이북을 사용하는 에이전트는 기본 시작 흐름의 기본 시작 인텐트 경로에서 호출 컴패니언 SMS 전송을 지원하지 않지만 표준 흐름에서 호출 컴패니언 SMS 옵션을 사용 설정할 수 있습니다.
  • 플레이북은 전화 시스템의 DTMF 입력을 지원하지 않습니다.

언어 지원

언어 참조플레이북 열을 참고하세요. 플레이북으로 표시된 언어는 gemini-2.0-flashgemini-1.5-flash-002 모델을 사용하여 품질 테스트를 거쳤습니다.

영어가 아닌 언어를 사용하는 경우:

  • 대부분의 경우 플레이북 안내에는 영어를 사용하세요. 특정 언어 및 사용 사례의 경우 대상 언어로 추가 지침을 제공하면 약간 더 나은 대답을 얻을 수 있습니다.
  • 플레이북 안내에서 언어 지원을 선언합니다. 예를 들어 '항상 프랑스어로 답변해 줘'라고 말할 수 있습니다.
  • 타겟 언어로 예시를 정의합니다.

모델 지원

플레이북에서 사용되는 LLM 모델은 다음 위치에서 선택할 수 있습니다.

  • 에이전트 수준에서 LLM 모델을 선택합니다.

    • 대화형 에이전트 콘솔 에이전트 설정 -> 생성형 AI -> 플레이북에서 사용 가능한 모든 모델의 드롭다운에서 표시 이름으로 모델을 선택합니다.
    • API를 사용하여 에이전트 설정을 업데이트하는 경우 GenerativeSettings.llm_model_settings.model 필드에 모델 이름을 지정합니다 (GenerativeSettings 참고).
  • 요청 수준에서 모델 선택을 재정의합니다.

    • 대화형 에이전트 콘솔 시뮬레이터에서 플레이북을 테스트할 때 드롭다운에서 표시 이름으로 모델을 선택합니다.
    • API를 통해 에이전트를 테스트하는 경우 DetectIntentRequest.query_params.llm_model_settings.model 필드에 모델 이름을 지정합니다 (DetectIntentRequest 참고).
모델 이름 모델 사양 출시 단계
gemini-2.5-flash Gemini 2.5 Flash GA
gemini-2.5-flash-lite Gemini 2.5 Flash-Lite GA
gemini-2.0-flash-001 Gemini 2.0 Flash GA
gemini-2.0-flash-lite-001 Gemini 2.0 Flash-Lite GA
gemini-1.5-flash-001 Gemini 1.5 Flash 기존
gemini-1.5-flash-002 Gemini 1.5 Flash 기존

리전 지원

플레이북은 다음 지역에서 지원됩니다.

  • global
  • asia-south1
  • asia-southeast1
  • asia-southeast2
  • asia-northeast1
  • australia-southeast1
  • eu(멀티 리전)
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
  • europe-west6
  • northamerica-northeast1
  • us(멀티 리전)
  • us-central1
  • us-east1
  • us-west1

플레이북 데이터

플레이북은 다음 데이터로 구성됩니다.

  • 플레이북 이름: 개발자와 LLM이 플레이북에서 처리하는 태스크를 이해하는 데 도움이 되는 자연어로 된 간결한 이름입니다.
  • 목표: 플레이북이 수행해야 하는 작업에 대한 대략적인 설명
  • 지침: 목표를 달성하기 위해 수행해야 하는 프로세스 단계 정의
  • 예시: LLM의 사실상 퓨샷 프롬프트 예시인 샘플 대화
  • 파라미터: 사용자 입력, 사용자 시스템 정보, 작업 결과 등과 같은 대화 정보를 저장하는 데 사용됩니다.

LLM 프롬프트

대화형 에이전트 (Dialogflow CX)는 각 대화 턴에 대해 설계 시 플레이북 데이터와 런타임 대화 데이터를 사용하여 토큰 한도 내에서 LLM 프롬프트를 만듭니다. 이 프롬프트의 내용은 다음과 같이 요약됩니다. 여기서 헤더는 설명용이며 프롬프트의 일부가 아닐 수도 있습니다.

# INTERNAL_SYSTEM_PROMPT
<you cannot see or edit this>

# INTERNAL_SYSTEM_EXAMPLES
<you cannot see or edit this>

# AVAILABLE_TOOLS_TO_CURRENT_PLAYBOOK
<tool names and schemas, for example...>

## Tool: my_datastore
   description: blah
   input: blah
   output: blah

## Tool: some_other_custom_tool
   description: blah
   input: blah
   output: blah

# PLAYBOOK
<verbatim Goal and Instructions that you provide in the console>

# PLAYBOOK_EXAMPLES
<as many Examples for the current Playbook as can fit in the prompt>

## Example 1

## Example 2
..
..
..
## Example N (up to the input token limit)

# CURRENT_CONVERSATION
<the conversation up to this point w/ some caveats...>

* Caveat 1: If there was a transition from Playbook A -> Playbook B, the
  Conversation that happened in Playbook A is summarized and provided as context
* Caveat 2: If there was a transition from Flow A -> Playbook A, the
  Conversation that happened prior to the entry of Playbook A is summarized and
  provided to the Playbook

플레이북 유형

플레이북을 만들 때 원하는 플레이북 유형(작업 플레이북 또는 루틴 플레이북)을 선택합니다.

작업 플레이북

작업 플레이북은 원래 유형의 플레이북입니다. 복잡한 작업을 재사용 가능한 작은 하위 작업으로 나누는 데 사용됩니다. 각 단계가 입력 및 출력 매개변수를 통해 통신하는 구성적 대화 단계를 모델링하는 데 사용됩니다.

다음은 다른 작업 플레이북 (피호출자)을 호출하는 작업 플레이북 (호출자)을 보여줍니다.

한 작업 플레이북에서 다른 작업 플레이북 호출

  1. 호출자가 호출 수신자를 시작합니다.
  2. 호출자가 피호출자에게 필요한 입력 매개변수를 제공합니다.
  3. 호출된 함수는 이 정보를 처리하고 지정된 기능을 실행하며 출력 매개변수를 반환합니다.
  4. 호출자가 호출 수신자로부터 매개변수를 수신합니다.

루틴 또는 작업 플레이북은 다른 작업 플레이북을 호출할 수 있지만 작업 플레이북은 다른 루틴 플레이북을 호출할 수 없습니다.

루틴 플레이북

루틴 플레이북은 새로운 유형의 플레이북입니다. 각 단계가 완료되고 독립적인 순차적 대화 단계를 모델링하는 데 사용됩니다. 태스크 플레이북을 호출하여 큰 작업을 더 작은 하위 작업으로 분해할 수 있으며 다른 루틴 플레이북이나 흐름으로 전환할 수 있습니다.

다음은 루틴 플레이북 (A)에서 다른 루틴 플레이북 (B)으로 전환하고 흐름 (C)으로 전환하는 과정을 보여줍니다.

한 루틴 플레이북이 다른 루틴 플레이북을 호출함

  1. 루틴 플레이북 A는 시작할 때 세션 매개변수를 읽고 종료 직전에 세션 매개변수를 쓸 수 있습니다.
  2. 루틴 플레이북 A가 종료되고 루틴 플레이북 B로 전환됩니다.
  3. 루틴 플레이북 B는 시작 시 세션 파라미터를 읽고 종료 직전에 세션 파라미터를 씁니다.
  4. 루틴 플레이북 B가 종료되고 흐름 C로 전환됩니다.
  5. 흐름 C는 세션 매개변수를 읽고 쓸 수 있습니다.

루틴 플레이북이 다른 루틴 플레이북이나 흐름으로 전환되지 않으면 세션이 마지막 활성 흐름으로 돌아가거나 활성 흐름이 없는 경우 종료됩니다.

루틴 플레이북에는 다음과 같은 매개변수 관리 동작이 있습니다.

  • 루틴 플레이북이 입력되면 입력 매개변수에 동일한 이름의 세션 매개변수와 동일한 값이 할당됩니다.
  • 루틴 플레이북이 종료되면 출력 매개변수의 값을 생성하고 동일한 이름의 세션 매개변수에 할당합니다.

플레이북 유형 비교

카테고리 Task 플레이북 루틴 플레이북
지연 시간 작업 플레이북이 다른 작업 플레이북을 호출할 때마다 LLM 호출이 발생합니다. 하나의 대화 턴에서 긴 태스크 플레이북 체인의 경우 지연 시간이 늘어날 수 있습니다. 일련의 전환에서 각 루틴 플레이북은 단일 대화 턴 내에서 발생하므로 LLM 호출이 하나만 있고 지연 시간이 개선됩니다.
매개변수 재생성 태스크 플레이북이 다른 태스크 플레이북을 호출하는 경우 매개변수 값을 재생성해야 합니다. 태스크 플레이북의 체인이 길면 이 재생성으로 인해 컨텍스트가 손실될 수 있습니다. 루틴 플레이북은 매개변수에 세션 스토리지를 사용하여 더 안정적인 컨텍스트를 만듭니다.
세션 매개변수 통합 태스크 플레이북은 세션 매개변수와 잘 연동되지 않으며 대신 입력 및 반환 매개변수를 정의해야 합니다. 루틴 플레이북은 세션 매개변수와 잘 호환됩니다.
재사용 가능성 모든 작업 플레이북에는 고정된 상위/하위 관계가 있으므로 작업이 긴밀하게 연결됩니다. 루틴 플레이북은 서로 독립적으로 정의할 수 있습니다.

기본 플레이북

대화형 에이전트 콘솔을 사용하여 생성형 에이전트를 만들면 기본 생성형 플레이북이 자동으로 생성됩니다.

기본 플레이북은 대화 시작점이므로 다른 플레이북과 몇 가지 중요한 차이점이 있습니다.

  • 기본 플레이북은 이전 대화 차례에 대한 요약을 받지 않습니다.
  • 기본 플레이북은 입력 매개변수를 정의하거나 수신할 수 없습니다.

플레이북 만들기

플레이북을 만들려면 다음 안내를 따르세요.

  1. 콘솔의 왼쪽 탐색에서 플레이북 아이콘을 클릭합니다.
  2. 새로 만들기 버튼을 클릭합니다.
  3. 루틴 또는 작업 플레이북 유형을 선택합니다.
  4. 플레이북 데이터를 제공합니다.

AI 생성을 사용하여 플레이북 만들기

플레이북을 만들면 생성형 AI 패널이 열립니다. 이를 사용하여 플레이북 데이터를 생성할 수 있습니다.

플레이북 가져오기 및 내보내기

대화형 에이전트 콘솔을 사용하여 플레이북을 만든 후 다른 에이전트에서 사용할 수 있도록 플레이북을 내보낼 수 있습니다. 플레이북을 내보내려면 다음 단계를 따르세요.

  1. 플레이북 목록으로 이동합니다.
  2. 내보낼 플레이북의 내보내기 버튼을 클릭합니다.
  3. 내보내기 옵션을 선택합니다.
  4. 내보내기를 클릭합니다.

이전에 내보낸 플레이북을 가져오려면 다음 단계를 따르세요.

  1. 플레이북 목록으로 이동합니다.
  2. 가져오기를 클릭합니다.
  3. 가져오기 옵션을 선택합니다.
  4. 가져오기를 클릭합니다.