플레이북 이름은 명확하고 설명적이며 자연스러운 영어여야 합니다. 이렇게 하면 런타임 시 AI 생성기의 성능이 향상됩니다.
예를 들어 '고객 고객센터 플레이북'은 'company_specialist'보다 낫습니다.
모든 이름은 영문 알파벳과 공백을 포함하여 64자(영문 기준) 이하여야 합니다.
간결한 목표
목표는 플레이북의 목적을 간결하게 설명해야 합니다.
고품질 지침 제공
지침은 다음과 같아야 합니다.
최종 사용자 문제를 해결하기 위한 단계별 접근 방식을 반영해야 합니다.
높은 수준의 지침을 제공하는 간결한 자연어 문장이어야 합니다.
명확하고 도구 사용 시나리오를 지정해야 합니다.
각 플레이북에 대해 하나 이상의 예 제공
플레이북마다 하나 이상의 예가 있어야 하지만 4개 이상 있는 것이 좋습니다.
예시에는 해피 패스 시나리오가 포함되어야 합니다.
예가 충분하지 않으면 플레이북에서 예측할 수 없는 동작을 보일 수 있습니다.
플레이북이 예상한 방식으로 응답하지 않거나 작동하지 않으면 예시가 누락되었거나 잘못 정의된 것일 수 있습니다.
예시를 개선하거나 새 예시를 추가해 보세요.
지침 및 예시의 정밀도
명확하고 설명적인 지침을 작성하면 도움이 되지만 실제로 플레이북 동작의 정확성을 결정하는 것은 예시의 품질과 수량입니다.
즉, 완벽하게 정확한 지침을 작성하는 것보다 예시를 철저하게 작성하는 데 더 많은 시간을 할애하세요.
예시의 참조 도구
플레이북이 도구를 사용하여 응답을 제공하도록 설계된 경우 이 요청 유형에 해당하는 예시의 도구를 참조하세요.
도구 스키마 operationId 필드
도구에 대한 스키마를 정의할 때는 operationId 값이 중요합니다.
플레이북 지침에서 이 값을 참조합니다.
이 필드의 이름 지정 권장사항은 다음과 같습니다.
문자, 숫자, 밑줄만 사용할 수 있습니다.
스키마에 설명된 모든 operationId 간에 고유해야 합니다.
제공된 기능을 반영한 의미 있는 이름이어야 합니다.
도구 스키마 검증
도구 스키마를 검증해야 합니다.
Swagger Editor를 사용하여 openAPI 3.0 스키마 문법을 확인할 수 있습니다.
빈 도구 결과 처리
플레이북이 대답을 위한 정보를 얻는 데 도구를 사용할 때 도구 결과가 비어 있으면 예기치 않은 플레이북 동작이 발생할 수 있습니다. 경우에 따라 플레이북 AI 생성기가 도구 결과 대신 대답으로 정보를 할루시네이션합니다.
이를 방지하려면 플레이북 AI 생성기가 자체적으로 대답을 시도하지 않도록 구체적인 요청 사항을 추가하면 됩니다.
일부 사용 사례에서는 플레이북 대답이 도구 결과 또는 제공된 데이터에 충분한 근거를 두고 플레이북 AI 생성기의 지식만을 기준으로 대답을 완화해야 합니다.
할루시네이션 완화를 위한 요청 사항 예:
'도구를 사용해 모든 사용자 질문에 대답해야 합니다.'
'도구에서 데이터를 다시 가져올 수 없는 경우 사용자 쿼리에 대한 답을 모른다고 대답합니다.'
'도구에서 데이터를 다시 가져올 수 없는 경우 대답을 제공하지 않습니다.'
Gemini로 스키마 생성
Gemini는 스키마를 자동으로 생성할 수 있습니다.
예를 들어 'Google Calendar용 openAPI 3.0 스키마 예시를 만들어 줘'라고 입력해 보세요.
집중적인 플레이북
크고 복잡한 플레이북을 만들지 마세요.
각 플레이북은 구체적이고 명확한 태스크를 수행해야 합니다.
복잡한 플레이북의 경우 더 작은 하위 플레이북으로 나누는 것이 좋습니다.
루프 및 반복 방지
지침에 에이전트를 연결할 때는 루프나 재귀를 만들지 마세요. 현재 플레이북을 직접 또는 간접적으로 호출한 상위 플레이북으로 라우팅하려고 하면 루프가 발생할 수 있습니다.
예시에 라우팅 정보 제공
플레이북이 다른 플레이북으로 라우팅되어야 하는 경우 이 정보를 예시에 제공해야 합니다.
이는 입력 및 출력 예시 섹션의 출력 정보가 있는 종료 예시 필드의 예시입니다.
예를 들어 이 필드의 마지막 문장은 '추가 쿼리를 위해 기본 플레이북으로 다시 라우팅'일 수 있습니다.
맞춤설정에 대화형 에이전트(Dialogflow CX) Messenger JavaScript 함수 사용
대화형 에이전트 (Dialogflow CX) Messenger를 사용할 때 사용자 맞춤설정 정보를 웹 인터페이스에서 플레이북으로 전송하는 데 다음 함수가 유용합니다.
생성형 기능은 일반적으로 응답을 생성하는 데 몇 초 또는 수십 초가 걸립니다. 플레이북은 대화의 자연스러움을 향상시키지만 긍정적인 최종 사용자 경험을 유지하려면 응답 시간을 관리하는 것이 중요합니다. 다음은 실적을 최적화하기 위한 몇 가지 전략입니다.
생성형 기능 사용 균형 유지
여러 생성형 기능을 실행하는 데 필요한 시간과 이러한 기능이 대화에 가져다주는 가치 간의 균형을 신중하게 고려하세요.
이러한 기능이 사용자의 목표 달성에 크게 기여하지 않는다면 과도하게 사용하지 마세요.
생성형 기능 입력 최소화
AI 생성기가 유용한 대답을 생성하는 데 필요한 최소한의 정보를 수집하고 처리하는 것을 목표로 합니다. 이렇게 하면 처리 시간이 크게 줄어듭니다.
컨텍스트 캐싱 사용
도구를 통해 Gemini를 사용 중이고 초기 컨텍스트가 큰 경우 Vertex AI 컨텍스트 캐싱을 사용하여 캐싱 정보를 살펴보고 동일한 데이터를 반복적으로 요청하지 않도록 합니다.
속도에 관한 고정 응답 구현:
애플리케이션에 고유한 동적 콘텐츠가 필요하지 않은 경우 Firebase와 같은 기존 데이터베이스에 자주 사용되는 응답을 저장하는 것이 좋습니다.
사전 정의되어 있고 쉽게 사용할 수 있으므로 이러한 고정 응답은 즉석에서 답변을 계산해야 하는 생성형 기능보다 훨씬 빠른 응답 시간을 제공합니다.
AI 생성기에 간결한 플레이북 응답 생성 지시
텍스트 입력 및 출력의 경우 AI 생성기 응답 시간은 사용 중인 모델과 출력 길이에 따라 크게 달라집니다. 짧은 대답은 실적을 크게 개선할 수 있습니다. 입력 길이도 고려되지만 출력 길이가 더 큰 영향을 미칩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003ePre-GA products and features, including this one, are subject to the "Pre-GA Offerings Terms," are available "as is," and may have limited support as outlined in the Service Specific Terms.\u003c/p\u003e\n"],["\u003cp\u003eCreating effective playbooks involves using natural language for names, defining concise goals, providing clear instructions, and including at least four examples that illustrate happy path scenarios.\u003c/p\u003e\n"],["\u003cp\u003eThe accuracy of a playbook's behavior is primarily determined by the quality and quantity of its examples, so focus on developing thorough examples rather than overly precise instructions.\u003c/p\u003e\n"],["\u003cp\u003eFor tool-reliant playbooks, ensure that examples reference the tools, that the tool schema's \u003ccode\u003eoperationId\u003c/code\u003e is appropriately named, and that instructions are added to prevent unpredictable behavior if tools return empty results.\u003c/p\u003e\n"],["\u003cp\u003eOptimizing playbook performance involves balancing generative feature usage, minimizing input, using context caching when necessary, and instructing the AI Generator to produce concise responses to reduce response times.\u003c/p\u003e\n"]]],[],null,["# Playbook best practices\n\n| **Note:** The AI Applications console still refers to playbooks as **agents** . This will be updated to **playbook** soon in the console.\n\nThe following best practices can help you build robust agents.\n\nPlaybook name in natural language\n---------------------------------\n\nPlaybook names should be clear, descriptive, and in natural English. This helps\nAI Generator's performance at runtime.\nFor example, \"Customer Help Center Playbook\" is better than \"company_specialist\".\n\nKeep all names under 64 characters, including English alphabets and spaces.\n\nConcise goals\n-------------\n\nGoals should be a concise description of the playbook's purpose.\n\nProvide quality instructions\n----------------------------\n\nInstructions should:\n\n- reflect the step-by-step approach to solving an end-user problem\n- be concise natural language sentences of high level instructions\n- be straightforward and specify the scenarios for tool uses\n\nAt least one example for each playbook\n--------------------------------------\n\nYou should have at least one\n[example](/dialogflow/vertex/docs/concept/examples)\nfor each playbook,\nbut it is recommended to have at least four.\nExamples should include happy path scenarios.\n\nWithout enough examples,\na playbook is likely to result in unpredictable behavior.\nIf your playbook is not responding or behaving in the manner you expect,\nmissing or poorly defined examples are likely the cause.\nTry improving your examples or adding new ones.\n\nPrecision of instructions and examples\n--------------------------------------\n\nWhile it helps to write clear and descriptive instructions,\nit's really the quality and quantity of your examples\nthat determine the accuracy of the playbook's behavior.\nIn other words,\nspend more time writing thorough examples\nthan writing perfectly precise instructions.\n\nReference tools in examples\n---------------------------\n\nIf the playbook is designed to provide responses by using tools, reference the\ntools in the examples corresponding to this type of request.\n\nTool schema `operationId` field\n-------------------------------\n\nWhen defining schemas for your tools,\nthe `operationId` value is important.\nYour playbook instructions will reference this value.\nThe following are naming recommendations for this field:\n\n- Letters, numbers and underscores only.\n- Must be unique among all `operationId`s described in the schema.\n- Must be a meaningful name reflecting the capability provided.\n\nTool schema validation\n----------------------\n\nYou should validate your tool schema.\nYou can use the\n[Swagger Editor](https://editor.swagger.io/)\nto check your openAPI 3.0 schema syntax.\n\nHandle empty tool results\n-------------------------\n\nWhen your playbook relies on a tool to inform its response, an empty tool result\ncan lead to unpredictable playbook behavior. Sometimes, the playbook AI\nGenerator will hallucinate information in a response in lieu of a tool result.\nTo prevent this, you can add specific instructions to ensure the playbook\nAI Generator doesn't attempt to answer on its own.\n\nSome use cases require playbook responses to be well grounded in tool results or\nprovided data and need to mitigate responses based only on the playbook\nAI Generator's knowledge.\n\nExamples of instructions to mitigate hallucinations:\n\n- \"You must use the tool to answer all user questions\"\n- \"If you don't get any data back from the tool, respond that you don't know the answer to the user's query\"\n- \"Don't make up an answer if you don't get any data back from the tool\"\n\nGenerate a schema with Gemini\n-----------------------------\n\n[Gemini](https://gemini.google.com/)\ncan generate a schema for you.\nFor example,\ntry \"can you create an example openAPI 3.0 schema for Google Calendar\".\n\nFocused playbooks\n-----------------\n\nAvoid creating very large and complex playbooks.\nEach playbook should accomplish a specific and clear task.\nIf you have a complex playbook,\nconsider breaking it down into smaller sub-playbooks.\n\nAvoid loops and recursion\n-------------------------\n\nDon't create loops or recursion when linking agents\nin your instructions. A loop can occur if you try routing to an ancestor playbook that, directly or indirectly, called the current one.\n\nProvide routing information to examples\n---------------------------------------\n\nWhen a playbook should route to another playbook,\nyou should provide this information to the examples.\nThis is provided to an example from the **End example with output information**\nfield of the **Input \\& Output** example section.\n\nFor instance,\nthe final sentence of this field could be\n\"Reroute back to the default playbook for further queries.\".\n\nUse Conversational Agents (Dialogflow CX) Messenger JavaScript functions for personalization\n--------------------------------------------------------------------------------------------\n\nWhen using Conversational Agents (Dialogflow CX) Messenger,\nthe following functions are useful to send user personalization\ninformation from the web interface to the playbook:\n\n- [setQueryParameters](/dialogflow/cx/docs/concept/integration/dialogflow-messenger/javascript-functions#setqueryparameters)\n- [setContext](/dialogflow/cx/docs/concept/integration/dialogflow-messenger/javascript-functions#setcontext)\n\nPlanning for performance\n------------------------\n\nGenerative features typically require several seconds or even tens of\nseconds to generate a response. While playbooks enhance conversational\nnaturalness, it's crucial to manage response times to maintain a positive\nend-user experience. Here are some strategies for optimizing\nperformance:\n\n- **Balance Generative Feature Usage**\n\n Carefully consider the trade-off between the time required to execute multiple\n generative features and the value they bring to the conversation.\n Avoid overusing these features if they don't significantly contribute to the\n user's goal.\n- **Minimize Generative features Input**\n\n Aim to gather and process the minimum amount of information required for an\n AI Generator to generate a useful response. This can reduce processing time\n significantly.\n- **Use Context Caching**\n\n If you're using Gemini through a tool and have a large initial context,\n explore caching information using\n [Vertex AI Context Caching](/vertex-ai/generative-ai/docs/context-cache/context-cache-overview)\n to avoid repetitive requests for the same data.\n **Implement fixed responses for speed:**\n\n If your application doesn't require unique, dynamic content, consider\n storing frequently used responses in a traditional database like Firebase.\n Because they are predefined and readily available, these fixed responses\n provide much faster response times than a generative feature that needs to\n calculate an answer on the fly.\n- **Instruct the AI Generator to produce Concise Playbook Responses**\n\n For text input and output, the AI Generator response time is highly dependent on the\n model being used and the **output** length. Short responses can significantly\n improve performance. While input length also factors in, output length has a\n larger impact."]]
