# AI Agent

### [![Response_AiAgent_Reset.png](https://simlab-soft.com/help/uploads/images/gallery/2026-03/scaled-1680-/5Y3response-aiagent-reset.png) ](https://simlab-soft.com/help/uploads/images/gallery/2026-03/5Y3response-aiagent-reset.png)AI Agent Reset Chat History

[![image.png](https://simlab-soft.com/help/uploads/images/gallery/2026-03/scaled-1680-/FTTimage.png)](https://simlab-soft.com/help/uploads/images/gallery/2026-03/FTTimage.png)The **AI Agent Reset Chat History** node enables the system to clear and reset the ongoing conversation history for a specific AI Agent. It is typically used when you want the AI to start a completely fresh interaction or switch to a new scenario without being influenced by the context of any prior messages.

### ![Response_AiAgent_SendMessage.png](https://simlab-soft.com/help/uploads/images/gallery/2026-03/scaled-1680-/response-aiagent-sendmessage.png) AI Agent Send Message

[![image.png](https://simlab-soft.com/help/uploads/images/gallery/2026-03/scaled-1680-/jCDimage.png)](https://simlab-soft.com/help/uploads/images/gallery/2026-03/jCDimage.png)

The **AI Agent Send Message** node enables the system to send a specific text message to an assigned AI Agent for processing. The **Output Voice?** boolean parameter that dictates how the AI agent will deliver its response:

- **False:** The AI agent will respond with text.
- **True:** The AI agent will process the text message and respond with generated voice audio.

### ![Response_AiAgent_SendVoiceMessage.png](https://simlab-soft.com/help/uploads/images/gallery/2026-10/scaled-1680-/response-aiagent-sendvoicemessage.png) AI Agent Send Voice Message

Has one of your scene’s AI agents deliver a pre-recorded voice file to a user.

#### What it does

This node tells the AI agent you name to play a voice file for a user. You choose which agent speaks, who hears it, and which sound file to use. It’s a handy way to have an agent greet someone, give an instruction, or read out a scripted message without typing live text.

The node only sends the message — it doesn’t change the agent, the user, or the voice file in any way. Every value you feed in is also handed straight back out, so you can pass the same agent, user, or file along to the next node in your sequence.

#### Inputs

<table id="bkmrk-port-type-what-to-co"><thead><tr><th style="white-space: nowrap;">Port</th><th style="white-space: nowrap;">Type</th><th>What to connect</th></tr></thead><tbody><tr><td style="white-space: nowrap;">**Execute**</td><td style="white-space: nowrap;">Trigger</td><td>Wire this from the previous node’s Execute output.</td></tr><tr><td style="white-space: nowrap;">**AI Agent Name**</td><td style="white-space: nowrap;">Text</td><td>The name of the AI agent that should speak. Pick one of the agents set up in your scene.</td></tr><tr><td style="white-space: nowrap;">**User**</td><td style="white-space: nowrap;">User</td><td>The person who should hear the message. Leave it on **Host Only** to send it just to the host, or connect a user to target someone specific.</td></tr><tr><td style="white-space: nowrap;">**Voice File**</td><td style="white-space: nowrap;">Text</td><td>The name of the voice file the agent should play.</td></tr><tr><td style="white-space: nowrap;">**Output Voice?**</td><td style="white-space: nowrap;">True / false</td><td>Set to `true` to have the message played aloud as voice, or `false` to send it without sound. Defaults to `true`.</td></tr></tbody></table>

#### Outputs

<table id="bkmrk-port-type-what-you-g"><thead><tr><th style="white-space: nowrap;">Port</th><th style="white-space: nowrap;">Type</th><th>What you get</th></tr></thead><tbody><tr><td style="white-space: nowrap;">**Execute**</td><td style="white-space: nowrap;">Trigger</td><td>Fires once the node has finished.</td></tr><tr><td style="white-space: nowrap;">**AI Agent Name**</td><td style="white-space: nowrap;">Text</td><td>The same agent name you connected, passed along so you can reuse it.</td></tr><tr><td style="white-space: nowrap;">**User**</td><td style="white-space: nowrap;">User</td><td>The same user you connected, passed along unchanged.</td></tr><tr><td style="white-space: nowrap;">**Voice File**</td><td style="white-space: nowrap;">Text</td><td>The same voice file name you connected, passed along unchanged.</td></tr><tr><td style="white-space: nowrap;">**Output Voice?**</td><td style="white-space: nowrap;">True / false</td><td>The same true/false setting you connected, passed along unchanged.</td></tr></tbody></table>

#### Example

<table id="bkmrk-ai-agent-name-input-"><tbody><tr><td>**AI Agent Name** input</td><td>`Guide`</td></tr><tr><td>**User** input</td><td>Host Only</td></tr><tr><td>**Voice File** input</td><td>`welcome_message.wav`</td></tr><tr><td>**Output Voice?** input</td><td>`true`</td></tr><tr><td>**Voice File** output</td><td>`welcome_message.wav`</td></tr></tbody></table>


### [![Response_AiAgent_StartListen.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/response-aiagent-startlisten.png)](https://simlab-soft.com/help/uploads/images/gallery/2024-08/response-value-number-add.png) AI Agent Start Listen

![Ceiling Node.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/E5cimage.png)

The **AI Agent Start Listen node** is used to make the AI start listening to the user. When activated, this node enables the AI to process and listen to spoken input from the user, allowing for interactive conversations and commands within the VR environment.

#### Example

![image.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/UjYimage.png)

In this example, an AI Doctor is set up in the AI Agents window. This window can be accessed by clicking the Interaction icon in the viewport menu, then select the AI Agents, and then add the AI name with the desired instructions in the Instructions field. A variable is created to store the AI's responses.

![image.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/2wtimage.png)

The **AI Agent Start Listen node** is used to make the AI Agent named Doctor start listening to the user when the object named "Start" is triggered. This setup enables the AI to process and listen to user input as soon as the trigger event is activated.

<iframe allowfullscreen="allowfullscreen" height="314" src="https://www.youtube.com/embed/TdABZrHXY2g" width="560"></iframe>

---

### [![Response_AiAgent_StopListen.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/response-aiagent-stoplisten.png)](https://simlab-soft.com/help/uploads/images/gallery/2024-08/response-value-number-add.png) AI Agent Stop Listen

![Ceiling Node.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/Iwwimage.png)

The **AI Agent Stop Listen node** is used to make the AI stop listening to the user. When activated, this node halts the AI’s ability to process further user input, allowing the AI to respond based on the information gathered up to that point.

#### Example

![image.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/UjYimage.png)

In this example, an AI Doctor is set up in AI Agents window. This window can be accessed by clicking the Interaction icon in the viewport menu, then select the AI Agents, and then add the AI name with the desired instructions in the Instructions field. A variable is created to store the AI's responses.

![image.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/scaled-1680-/3UZimage.png)

The **AI Agent Stop Listen node** is used to stop the AI Agent from listening to the user when the "Stop" trigger event occurs. This allows the AI agent named Doctor to respond based on the input received before listening was stopped.

### [![Response_AiAgent_StopListen.png](https://simlab-soft.com/help/uploads/images/gallery/2024-09/response-aiagent-stoplisten.png)](https://simlab-soft.com/help/uploads/images/gallery/2024-08/response-value-number-add.png) AI Agent Stop Listen (Text)

[![image.png](https://simlab-soft.com/help/uploads/images/gallery/2026-03/scaled-1680-/Gldimage.png)](https://simlab-soft.com/help/uploads/images/gallery/2026-03/Gldimage.png)

The **AI Agent Stop Listen (Text) node** is used to make the AI stop listening to the user. When activated, this node halts the AI’s ability to process further user input, allowing the AI to respond based on the information gathered up to that point.

This node has an extra output "Spoken Text", when the node is activated, it outputs the input audio in text format.

---

### [![Response_Ai_Valid_Key.png](https://simlab-soft.com/help/uploads/images/gallery/2025-02/response-ai-valid-key.png)](https://simlab-soft.com/help/uploads/images/gallery/2024-08/response-value-number-add.png) Has Valid AI Key

![Ceiling Node.png](https://simlab-soft.com/help/uploads/images/gallery/2025-02/scaled-1680-/2Xximage.png)

<div class="flex-shrink-0 flex flex-col relative items-end" id="bkmrk--33"><div><div class="pt-0"><div class="gizmo-bot-avatar flex h-8 w-8 items-center justify-center overflow-hidden rounded-full"><div class="relative p-1 rounded-sm flex items-center justify-center bg-token-main-surface-primary text-token-text-primary h-8 w-8">  
</div></div></div></div></div>The **Has Valid AI Key** node checks whether a valid AI key is available for AI-related features in Sim Lab Composer. This node ensures that AI functionalities can operate properly by verifying the presence of an active and valid AI key.

#### Example

[![AI has key.JPG](https://simlab-soft.com/help/uploads/images/gallery/2025-03/ai-has-key.JPG)](https://simlab-soft.com/help/uploads/images/gallery/2025-02/lXbimage.png)

In this example, the **Has Valid AI Key** node is used at the start of the scene to check if the user has an activated AI key. The node is connected to a **Branch** node, where the **False** output (indicating no valid AI key) triggers a message in front of the user, informing them that the AI key must be activated.

<iframe allowfullscreen="allowfullscreen" height="314" src="https://www.youtube.com/embed/YEMeCS8QcFY" width="560"></iframe>

---

### ![Response_AiAgentKey_Set.png](https://simlab-soft.com/help/uploads/images/gallery/2026-10/scaled-1680-/response-aiagentkey-set.png) Set AI Key

Gives your experience an AI key, so its AI agents can answer without each user having to enter a key of their own.

#### What it does

Choose a key in the **AI Key** field. The list shows the AI keys saved on your SimLab account, by name and provider. To add one, pick **New key** at the end of the list, or create it on your [SimLab account page](https://www.simlab-soft.com/hub/account) under **API Keys** → **AI**. The experience keeps only a reference to the key, not the key itself.

When the node runs, it fetches the key from SimLab, checks it with the AI provider, and makes it available to every AI agent that uses that provider. The person running the experience must be **signed in** to SimLab — with any account, not necessarily yours. **Success** tells you whether it worked. It is `false` when the field is empty, when the key can’t be fetched (nobody is signed in, or the key was removed, switched off or has expired), or when the provider rejects the key. In a multi-user session, the key is fetched and used only by the host, who talks to the AI for everyone; the other participants never receive the key itself.

If an AI agent has no key for its provider — this node wasn’t run, or its key didn’t work — the agent falls back to the OpenAI key the person running the experience entered in the Viewer’s settings, if they have one.

#### Inputs

<table id="bkmrk-port-type-what-to-co-0"><thead><tr><th style="white-space: nowrap;">Port</th><th style="white-space: nowrap;">Type</th><th>What to connect</th></tr></thead><tbody><tr><td style="white-space: nowrap;">**Execute**</td><td style="white-space: nowrap;">Trigger</td><td>Wire this from the previous node’s Execute output.</td></tr><tr><td style="white-space: nowrap;">**AI Key**</td><td style="white-space: nowrap;">Text</td><td>The key to use. Pick one of your saved AI keys from the list, or create one with **New key**. The saved key already knows its provider.</td></tr></tbody></table>

#### Outputs

<table id="bkmrk-port-type-what-you-g-0"><thead><tr><th style="white-space: nowrap;">Port</th><th style="white-space: nowrap;">Type</th><th>What you get</th></tr></thead><tbody><tr><td style="white-space: nowrap;">**Execute**</td><td style="white-space: nowrap;">Trigger</td><td>Fires once the key has been fetched and checked with the AI provider, usually a moment after the node starts. It fires whether or not the key worked, so check **Success**.</td></tr><tr><td style="white-space: nowrap;">**Success**</td><td style="white-space: nowrap;">True / false</td><td>`true` if the key is ready for your AI agents. `false` if the field was empty, the key couldn’t be fetched, or the provider rejected the key. For the other participants in a multi-user session, it tells you whether the host could fetch the key.</td></tr></tbody></table>

#### Example

<table id="bkmrk-execute-input-wired-"><tbody><tr><td style="white-space: nowrap;">**Execute** input</td><td>Wired from the **Scene Start** event</td></tr><tr><td style="white-space: nowrap;">**AI Key** input</td><td>The saved key “Patient Sim – OpenRouter”, picked from the list</td></tr><tr><td style="white-space: nowrap;">**Success** output</td><td>`true`</td></tr></tbody></table>

#### Tips

- **Don’t keep a pasted key.** If you paste a provider key straight into the field, Composer offers to store it on SimLab for you — accept. If you decline, the key itself travels inside the experience file, and the node shows a warning.
- **Gemini, OpenRouter and other providers.** Create the key as an OpenAI key with **Custom endpoint** set to the provider’s address, then give the agent the matching **Provider** in **Set AI Agent Model**. The addresses are listed under *Using AI Providers and API Keys in SimLab Composer* on this page.
- **Set the key once, at the start.** Run this node from **Scene Start**, then use **Success** (or the **Has Valid AI Key** node) to tell the user when AI features aren’t available.
- **Older experiences** may contain the previous version of this node, which had a separate **Provider** input and took the key itself. It keeps working; new graphs should use this one.

### ![Response_AiModel_Set.png](https://simlab-soft.com/help/uploads/images/gallery/2025-07/response-aimodel-set.png) **Set AI Agent Model**

![Ceiling Node.png](https://simlab-soft.com/help/uploads/images/gallery/2025-07/scaled-1680-/R5Nimage.png)

<div class="flex-shrink-0 flex flex-col relative items-end" id="bkmrk--47"><div><div class="relative p-1 rounded-sm flex items-center justify-center bg-token-main-surface-primary text-token-text-primary h-8 w-8">  
</div></div></div>The **Set AI Agent Model** node is used to assign a specific AI provider and model to an AI agent in your VR experience. This ensures the AI agent will operate using the selected provider and model for any interactions that occur in the scene. You can choose the AI agent you have created, specify the provider (OpenAI, Gemini, or OpenRouter), and define the model name.

#### Example

[![image.png](https://simlab-soft.com/help/uploads/images/gallery/2025-07/scaled-1680-/XCzimage.png)](https://simlab-soft.com/help/uploads/images/gallery/2025-07/XCzimage.png)

In this example, the **Set AI Agent Model** node is triggered by pressing a button in the VR scene. When the button is clicked, the node assigns the “Patient” AI agent to the OpenAI provider and sets the model to GPT‑4. This setup allows the AI agent to function with the defined provider and model as soon as the event is triggered.

Check this **[tutorial](http://youtube.com/watch?v=qzqNtXBTGY4)** for more about this node.

<iframe allowfullscreen="allowfullscreen" height="314" src="https://www.youtube.com/embed/qzqNtXBTGY4" width="560"></iframe>

---

### Using AI Providers and API Keys in SimLab Composer

The AI agents in your VR experiences can use **OpenAI**, or any provider with an OpenAI-compatible address such as **Google Gemini** and **OpenRouter**. Setting one up takes three steps:

1. **Save the key.** On your [SimLab account page](https://www.simlab-soft.com/hub/account), open **API Keys** → **AI** → **New AI key** (or pick **New key** in the Set AI Key node). Paste the key from your provider. For OpenAI, that’s all. For another provider, open **Custom endpoint** and enter its **Base URL** from the list below.
2. **Set AI Key** — pick that saved key in the node, so the experience gives it to its agents.
3. **Set AI Agent Model** — set the agent’s **Provider** to the matching **Provider URL** below, and choose a model.

**The two addresses must match exactly.** An agent uses the key whose Base URL, followed by `/chat/completions`, is its Provider URL. If they differ even slightly, the agent doesn’t get your key and falls back to the OpenAI key the person running the experience entered in the Viewer’s settings, if any.

#### Providers and models

The models below are examples. Providers add and retire models often, so check your provider for the current names.

**1. OpenAI**

- **Base URL:** leave Custom endpoint empty
- **Provider URL:** `https://api.openai.com/v1/chat/completions`
- **Models:** `gpt-4.1`, `gpt-4`, `gpt-3.5-turbo`

**2. Google Gemini**

- **Base URL:** `https://generativelanguage.googleapis.com/v1beta/openai`
- **Provider URL:** `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`
- **Models:** `gemini-2.0-flash`

**3. OpenRouter**

- **Base URL:** `https://openrouter.ai/api/v1`
- **Provider URL:** `https://openrouter.ai/api/v1/chat/completions`
- **Models:** `nvidia/llama-3.3-nemotron-super-49b-v1:free`

#### What each key can do

- **OpenAI keys** work with chat, text-to-speech and speech-to-text.
- **Gemini and OpenRouter keys** work with text chat only.