## Overview This template provides a framework for designing experiments where humans and AI language models (LLMs) can interact in a conversational format. While the template uses a conspiracy theory debunking example, it can be modified for various research purposes. ## Request If you use our template (.QSF) to set up your research, we would appreciate it if you cite our paper when describing your method: > [Durably reducing conspiracy beliefs through dialogues with AI](https://osf.io/preprints/psyarxiv/xcwdn) ## Video Tutorial Please watch the video below for a complete tutorial on how to use the human-AI interaction Qualtrics template. <iframe width="660" height="315" src="https://www.youtube.com/embed/piLMZbLhqMk?si=GnpnV4o0A2-ZC8EH" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> ## Key Components 1. **OpenRouter Integration**: Uses OpenRouter API to interact with various LLMs. 2. **Dynamic Prompts**: Allows for personalized AI responses based on user input. 3. **Multi-round Conversation**: Supports a three-round conversation between the user and the AI. 4. **Web Service and JavaScript API Calls**: Demonstrates two methods of calling the LLM API. ## Setup Instructions 1. **OpenRouter Account**: - Create an account at OpenRouter - Obtain an API key - Load funds if using paid models 2. **Qualtrics Survey Setup**: - Import the template (.qsf file) into Qualtrics - Navigate to the Survey Flow section 3. **API Configuration**: - Locate the "Embedded Data" section at the beginning of the Survey Flow - Replace `[Your API Key Here]` with your actual OpenRouter API key - Set the desired model in the `setModel` field (e.g., "openai/gpt-4-turbo") ## Customization Guide ### Modifying the AI Prompt 1. Locate the `setPrompt` embedded data field in the Survey Flow 2. Edit the prompt to suit your research needs 3. Use placeholders (e.g., `{{conspiracyTheory}}`, `{{userBeliefLevel}}`) for dynamic content ### Changing the Conversation Topic 1. Edit the initial questions in the "Questions (answers placed into prompt)" block 2. Update the system message in the `runFunction_1` block's JavaScript to reflect the new topic ### Adjusting Conversation Rounds - To add more rounds: 1. Duplicate the `runFunction` and `ConvoRound` blocks 2. Update the conversation history array in each new `runFunction` block 3. Increment the GPT response variable names (e.g., `GPTResponse4`, `GPTResponse5`) - To reduce rounds: 1. Remove the unnecessary `runFunction` and `ConvoRound` blocks 2. Update the Survey Flow to reflect the new structure ### Modifying Response Processing 1. Locate the JavaScript in the `runFunction` blocks 2. Edit the `sendChatToOpenRouter` function to change how responses are processed or saved ### Changing the LLM Model 1. Update the `setModel` embedded data field in the Survey Flow 2. Ensure the new model is supported by OpenRouter and adjust any model-specific parameters ## Advanced Modifications ### Custom API Integration To use a different API: 1. Update the API endpoint URL in the `sendChatToOpenRouter` function 2. Modify the request headers and body structure as required by the new API 3. Adjust the response parsing to match the new API's output format ### Adding Pre/Post Measures 1. Create new question blocks in Qualtrics 2. Add the blocks to the Survey Flow in the desired positions 3. Use embedded data to save responses and incorporate them into the AI conversation if needed ### Implementing Branching Logic 1. Use Qualtrics' Branch Logic in the Survey Flow to create conditional paths 2. Modify the conversation blocks to handle different scenarios based on user responses ## Troubleshooting - **API Errors**: Check the browser console for error messages. Ensure your API key is correct and you have sufficient funds. - **Long Load Times**: Increase the timeout value in the JavaScript API call if responses are consistently timing out. - **Unexpected AI Responses**: Review and refine your system message and prompts to guide the AI more effectively. ## Best Practices 1. Always test your modified survey thoroughly before deploying it to participants. 2. Monitor API usage to manage costs, especially when using paid models. 3. Regularly review and update your prompts to improve the quality of AI-human interactions. 4. Consider ethical implications and obtain necessary approvals for human-subject research involving AI interactions. ## Other Resources [[Technical details - embedded values and custom javascript]] [[Web service usage in Qualtrics LLM template]]