> For the complete documentation index, see [llms.txt](https://docs.aisera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisera.com/workflow-best-practices/hyperflow-best-practices.md). # Hyperflow Best Practices ## Design for user interaction Design user interaction before implementation so the Hyperflow behaves clearly across channels and sets the right expectations for users. Consider how users engage with the Hyperflow, how responses are presented, and where human oversight is needed. ### How do users interact with Hyperflows? Users interact with Hyperflows through channels integrated with the application. This is consistent across all types of flows and fulfillments. These channels include webchats, e-mail, SMS, instant messaging, using the **Notification Action**. A flow builder must explicitly add **Notification Actions** to the Hyperflow for security reasons. ### How are Hyperflow outputs formatted? By default, Hyperflows produce markdown-formatted output. You can change the formatting in one of two ways: 1. Include instructions in the prompt defining what the output should be. 2. For highly custom requirements, create display functions with user interaction nodes to output items such as custom display cards and charts. Prevent overloading a Hyperflow with any task that can be achieved with a workflow, such as formatting instructions. ### Balance automation with human oversight While Hyperflows can operate autonomously, determine appropriate points for human oversight and intervention, especially for critical decisions or complex scenarios. you can provide these using Hyperflow instructions and **User Interaction Nodes** in workflows used as functions. ## Hyperflow implementation After defining how users interact with a Hyperflow, the next step is to design how the Hyperflow works behind the scenes. Implementation decisions shape reliability, maintainability, and how well the Hyperflow handles real-world scenarios. ### Use structured and standardized approaches Implement Hyperflows using standardized patterns when possible to maintain consistency across your organization. This helps with maintainability and knowledge sharing. For example: * Create Hyperflows for specific use cases that span multiple external systems. For example, ordering a device during IT onboarding may require tasks in ServiceNow and a procurement system. You can also create Hyperflows for a single integration that supports multiple use cases, such as ticket management in ServiceNow. * When writing Hyperflow prompts, in addition to instructions for what Hyperflow should do, provide instructions for what it should not do and how it should handle exceptional scenarios. ### Implement proper error handling Design your Hyperflows with robust error handling mechanisms. * Consider how the workflow should respond to various failure scenarios, similar to how transient failures are handled in distributed environments with automatic retry mechanisms. * Plan for scenarios where API or Action executions fail. * Test thoroughly before deployment. ### **Break Hyperflows into manageable steps** For complex processes, break your Hyperflows into smaller, manageable steps that can be independently tested and verified. This approach resembles other workflow systems, where units of work are specified as steps with logical outlines. ### **Plan for data handling and privacy** Carefully consider what data your Hyperflow will handle and ensure proper privacy measures are in place. Follow best practices for Generative AI and Open Data to maintain transparency and appropriate data handling. ### Ending the Hyperflow execution * The underlying LLM determines when a Hyperflow ends execution — when the AI model decides that a user's request has been fulfilled, or cannot be fulfilled due to being out of scope, it ends execution. After that, you will see the Feedback buttons on the Conversation interface. * The phrases `That's all my ask` and `Thank you!` also end execution. * When a Hyperflow is finished, to trigger it again, your application needs to detect another Intent that triggers this Hyperflow. ## Tool design Tool design affects how reliably the Hyperflow can choose, interpret, and use available functions. Clear tool names, descriptions, and inputs reduce errors, improve decision-making, and make the system easier to maintain. ### Write clear tool descriptions Tool descriptions tell the LLM when and how to use a tool. Vague or misleading descriptions such as "Do not select this workflow" or "copied from bot" causes the LLM to misuse or ignore tools entirely. Write descriptions that state the tool's purpose clearly, for example: "Provides instructions for any article creation and management related queries." ### Use explicit parameter names and descriptions Parameter names such as `responseStr` or `output` give the LLM no information about what value to pass. Use names that describe the content, such as `instructions`, and provide a description for every parameter. Avoid markup such as HTML in descriptions. Plain text is clearer for the LLM. Always `required: true` on input parameters. ### Keep tools focused and limited in scope Each tool should do one thing well. Avoid multi-purpose tools that combine unrelated responsibilities. Limit Hyperflows to 10 tools or fewer as exceeding this can overwhelm the LLM's context and increases failure rates. ### Design for human understanding first If a tool is difficult for a human to understand, it will be difficult for the LLM to use correctly. Naming, descriptions, and structure should be clear to any team member reading them, not just the original author. ## Prompt design Prompt design shapes how the Hyperflow interprets instructions, uses tools, and responds across different scenarios. Clear prompt structure improves consistency, reduces ambiguity, and makes the flow easier to test and refine over time. ### Be explicit and unambiguous Write prompts in clear, precise, and complete language. Every instruction should have exactly one meaning and leave no room for interpretation. Ambiguous instructions lead to inconsistent behavior the LLM may interpret them differently across runs. ### Avoid conflicting instructions Contradictory instructions cause unpredictable behavior both between different executions and within the same execution. Review your prompts for logical consistency before deployment. ### Control instruction order carefully LLMs weight earlier instructions more heavily. Put your most critical rules first. Performing more critical or complex tasks early increases the chance of a successful execution. ### Add structured examples, especially for edge cases Examples teach LLMs more effectively than abstract rules. Include structured examples for failure scenarios and edge cases, not just the happy path. {% code overflow="wrap" %} ```xml add comment to ticketXXX [Step 1: MANDATORY CHECK - Parse request to separate ACTION from CONTENT] [Step 2: Identified ACTION words: "add comment"] [Step 3: Identified ticket ID: ticketXXX] [Step 4: Identified CONTENT: NONE] [Step 5: CRITICAL ERROR PREVENTION: Request contains only action verb and ticket ID. This would be INVALID to use 'add comment to ticketXXX' as comment content.] [Step 6: STOP - Must ask user for comment content] I can add a comment to ticketXXXfor you. What would you like the new comment to say? ``` {% endcode %} ### What to avoid in prompts * Do not reference variables that do not exist in the Hyperflow context. For example, do not reference the user's input and conversation history such as `${conversationContext.conversationHistory}`. * Do not expose internal tool names or system architecture — for example, do not reference internal function names like `finish_function` or `get_help_function` directly in user-facing logic. * Do not attempt to override out-of-scope handling. The Hyperflow engine manages out-of-scope requests, and trying to override this behavior can cause unpredictable results. ### Use the prompt optimizer Run your prompt through the built-in prompt optimizer to surface structural improvements, ambiguities, and ordering issues before deployment. Another optimization strategy is to ask an LLM to review your prompt: * Is this specific enough? * Are the instructions clear? Can the instructions be interpretted in different ways? * Do any rules contradict? * Are the tool and variable descriptions accurate and clear? ## Clean architecture Clean architecture makes Hyperflows easier to understand, test, and maintain. It also improves reliability by keeping logic clear, reducing unnecessary complexity, and helping the LLM operate within a predictable structure. ### Common design pitfalls The following pitfalls are common when designing Hyperflows. Each one can reduce reliability, make behavior harder to predict, and increase the effort required to maintain the flow over time. * **Too many tools:** More than 10 tools in a single Hyperflow overwhelms the LLM's context and increases failure rates. Keep your toolset focused. * **Scattered logic:** Logic split across the system prompt and multiple tools creates inconsistent behavior and makes flows difficult to maintain. Centralize logic in the prompt. * **Instructions hidden in tool outputs:** Output variables should carry data, not logic or instructions for the LLM. Embedding instructions inside output variable expressions makes your flow invisible and hard to debug. * **Over-engineered workflows:** Complexity is the enemy of reliability. Simple, focused flows outperform clever, complex ones. ### Clean architecture principles * Centralize logic in the Hyperflow prompt rather than distributing it across tools. * Keep each tool focused on a single responsibility. Avoid multi-purpose tools. * Minimize conversational branches inside workflows used as tools. * Use consistent naming, formatting, and patterns across the entire flow. * Use examples to eliminate ambiguity, examples teach LLMs better than abstract rules. ### Design for reliability AI agents follow instructions closely but will not challenge flawed decisions. As probabilistic systems, they can produce different outputs even under identical conditions. Design your Hyperflows as if you are onboarding a capable but very literal new team member. Clarity and precision in your instructions determine the quality of the result. ## Maintenance Maintain Hyperflows as active systems, not one-time implementations. Regular review, change tracking, and user feedback help keep them accurate, reliable, and aligned with evolving business needs. * **Regularly review and update your Hyperflows:** Review Hyperflows on a set schedule to keep them aligned with business goals and new platform capabilities. * **Use version control:** Track every Hyperflow change with version control and document what changed and why. * **Gather and act on user feedback:** Establish a process to collect, analyze, and apply feedback from Hyperflow interactions. ## Optimization Optimize Hyperflows for speed, clarity, and efficient use of context. Small design improvements can reduce latency, improve reliability, and make flows easier to maintain as they grow. ### Reduce unnecessary steps Optimize your Hyperflows by eliminating redundant steps and streamlining execution paths. Each unnecessary step adds latency, increases complexity, and creates more opportunities for failure. Remove steps that do not add clear value, and avoid using Hyperflows for tasks that a standard workflow can handle more predictably. When possible, simplify branching, reduce repeated tool calls, and pass only the information needed for the next action. ### Reduce perception of latency LLMs are inherently slow to respond. This is compounded with retrieval-augmented generation (RAG) that requires search and retrieval, followed by LLM summarization. Hyperflows and the RAG Action function support streaming of output without having to wait for the complete response to be generated. Leverage these to reduce the perception of latency. ### Optimize memory and context management During a conversation session, Hyperflows always have context of the conversation history. Additionally, Hyperflows provide three levels of memory for you to use: * **Context window:** a per-request short-term memory limited by the context window of the underlying AI model. The context window size will continue to expand in upcoming releases. * **Session Variables:** a per-session shared memory which can be used by all the flows that are triggered during a user session. Aisera provides Functions and Nodes to read from and write to this memory from Hyperflows and Workflows, respectively. * **Custom tables:** long-term memory that can be used across sessions. Aisera provides Functions and Nodes to read from and write to this memory from Hyperflows and Workflows, respectively. Using appropriate memory is critical to ensuring accuracy and performance. For example, * Avoid returning too much content from a function call to the Hyperflow context window. Instead, use pagination or post-process data using a workflow before returning only the necessary information to the Hyperflow. * Instead of passing information between Hyperflows and functions, use a session variable as shared memory.