> For the complete documentation index, see [llms.txt](https://docs.wem.io/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wem.io/platform/wemmodeler/agentic-ai/ai-user-interaction.md). # AI User Interaction ## AI User Interaction An AI agent can be reached in three ways: through a chatbox where the user types, through a voice chat where the user speaks, or with no interface at all, driven entirely from a flowchart. A conversation is not interchangeable between these: a conversation with a voice model can only be interacted with by voice, not by chat, and a conversation with a text model can only be interacted with by chat, not by voice. Which one applies is decided by the model the agent uses, not by which component is used on the page. The one exception is observation: a chatbox in read-only mode can display a voice conversation as a text transcript, without allowing the user to type into it through the read only mode. {% hint style="info" %} At the moment of writing this article only ChatGPT provides a model that supports real-time voice commands, this can change any time. {% endhint %} ## Text ### AI agent chatbox The **AI agent chatbox** component allows users to communicate with an AI agent in real time. It provides an interface where users can enter messages, receive responses, and continue an existing conversation. The chatbox does not create a conversation itself, it displays one: the conversation must already exist, and its ID is passed to the component.

#### Properties

Property	Input	Description
Conversation ID	Convo ID Function	The conversation to display, set with an AI agent conversation field. The chatbox shows the message history of this conversation and allows the user to continue it.
Readonly mode	Toggle	When enabled, the chatbox displays the conversation in real time but disables the input. The user can observe what is happening but cannot send messages or otherwise influence the interaction.

**Behavior**

Property	Description
Show function and tool calls	When enabled, the chatbox surfaces the function calls and hosted tool invocations made by the agent. Useful during development to see what the agent is doing. For end users, leaving this off keeps the conversation clean.
Show reasoning	When enabled, the chatbox shows the agent's reasoning steps. This only applies to models with reasoning capabilities.
Show system messages	When enabled, system messages, including the instruction sent to the agent and internal status messages, are visible in the chatbox. Make sure this is off in production.

**Appearance**

Property	Description
Display mode	Controls how the chatbox is positioned on the page. Normal flow renders the chatbox inline as part of the page layout. Fixed anchors the chatbox to a screen position regardless of scrolling, for a helper-style chatbot that stays visible while the user works.
Input placeholder text	The hint text shown in the message input field before the user types anything. Accepts a text literal or an expression.
Show timestamps	When enabled, each message shows the date and time it was sent.
Height	The height of the chatbox in pixels. Defaults to 500.

#### What the chatbox shows Beyond the messages themselves, the chatbox reflects the state of the conversation while the agent is working: * A loading indicator appears while the agent is processing, so the user can see that a response is on its way. * Markdown formatting is applied to agent messages only. Messages typed by the user are shown as plain text, so characters like `*` and `#` appear exactly as entered. * Function and tool calls are collapsible. Their arguments and results are shown as JSON when expanded. * Reasoning that arrives in multiple parts is shown as a single block per message rather than as separate fragments. * For messages produced by an **Invoke agent** node, the prompt and the payload are displayed separately instead of as one combined message. Which of these are visible depends on the Behavior properties above. The loading indicator and the markdown behaviour are always active. #### Read-only mode With **Read only mode** enabled, the chatbox becomes an observation surface. The conversation updates live, but the input is disabled. This supports a few patterns that do not involve the user talking to the agent at all: * A supervisor watching a conversation that another user is having. * A monitoring screen for a conversation being driven from a flowchart, with no human on the user side at all. * Playback of a historical conversation, for review or audit purposes. ## Audio ### The AI agent voice chat The **AI agent voice chat** component allows the user to hold a spoken conversation with an AI agent. The user starts a call, speaks, and hears the agent's response. As with the chatbox, the component displays an existing conversation rather than creating one. Voice conversations depend on the model, not on the component. Only realtime models support voice, which means the agent must be configured with an OpenAI realtime model such as `gpt-realtime-2`, `gpt-realtime-2.1` or `gpt-realtime-2.1-mini`. Placing the component on a page for an agent that uses a text-only model does not produce a working call. #### Requirements * An agent configured with an OpenAI realtime model. * An existing conversation, created with a **Create conversation** node. * A browser that permits microphone access. The user is asked for permission by the browser the first time a call is started. * The component is available from **5.2.1**, but **5.3** or later is advised. #### Properties | Property | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Conversation ID | The conversation the call belongs to, set with an **AI agent conversation** field. | | Title | The title text shown in the component when it is rendered. Accepts a text literal or an expression. | | Greeting instructions | Controls who speaks first. When left empty, the agent waits for the user to say something. When filled, the value is used as the instruction for the agent's greeting, so the agent opens the conversation before the user has said anything. Accepts a text literal or an expression. | | Voice | The name of the voice personality the agent speaks with. Which personalities are available depends on the chosen model. See OpenAI's [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations) guide for the voices supported by the realtime models. | {% hint style="info" %} Once the agent has produced audio in a call, the voice cannot be changed for the remainder of that call. {% endhint %} #### What the user experiences Rendered, the component shows a call icon, the **Title** text, and the current connection state below it. The user starts the call by selecting the icon, at which point the browser asks for microphone permission if it has not been granted yet. The connection state changes as the call is established, and the user can end the call from the same control. If **Greeting instructions** are set, the agent speaks first. Otherwise it listens and waits. #### Monitoring and transcript The chatbox component can still be useful for voice agents, a chatbox set to the same conversation id as a voice conversation can be used to see the conversation in text format. This can be done live or used to read back an earlier conversations. #### Tokens and cost Voice conversations consume tokens like any other conversation, and usage is recorded against the conversation in the same way. Both spoken input and spoken output are billed by the provider, and realtime models are priced differently from text models. A voice conversation is generally more expensive than the same exchange typed into a chatbox, which is worth taking into account when choosing an interaction style. Token counts for a conversation can be read with `InputTokenCount()` and `OutputTokenCount()`. #### Limitations * Voice is supported for OpenAI realtime models only. Other providers and other OpenAI models are text only. * The set of available options differs from text models. Reasoning effort is supported on the realtime models, while a maximum output token limit is not yet available for them. * Changing the model on an agent between a text model and a realtime model changes what the agent can do, and the conversation is re-created. ## Flowchart-driven Not every agent needs a user interface. An agent can be driven entirely from a flowchart, with the application deciding when to invoke it and what to do with the result. #### Driving an agent with no interface The **Invoke agent** node sends a prompt to an agent without requiring a user to interact with the agent directly. The response should be an agents function that is then ran like an a-synchronous task. This suits back-end work: classifying an incoming request, summarising a document, extracting data from texts/files, or making a decision that feeds into a deterministic flow. #### Reading the conversation A headless conversation is a normal conversation, stored and readable like any other. This means work done with no interface can still be surfaced afterwards: * A read-only chatbox on the conversation ID used by the send message node shows what the agent did, live or after the fact. * The AI expression functions report on the conversation from anywhere in the project, including `HasContent()`, `DateCreated()`, `DateModified()` and the token count functions. * A conversation started interaction can be handed to a user later, in a chatbox or a voice chat, with its context intact. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.wem.io/platform/wemmodeler/agentic-ai/ai-user-interaction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.