[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-18。"],[[["\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."]]
