In this Use Case we're setting up a Virtual User that reaches out to your external systems mid-conversation. It uses re-usable Authentication to look up customer or order data, querying ticket systems, or using any other APIs the bot needs to do its job. The Virtual User uses Nimbus' AI Workflow profile together with Extension Tools: Web Requests for any HTTP API, and MCP Servers for tool collections that speak the Model Context Protocol. 

The Virtual user also defines Intent-driven exits (Outcomes) for handling user-specific requests, optionally storing any intent responses (e.g. a retrieved account number or the customer name) in Parameters. Instead of a single fixed Success exit, the Virtual User now returns conversation result Outcomes you define on the Virtual User configuration, then map to Workflow exits.

💡Note: the terms “Intent” and “Outcome” are used interchangeably in the Virtual User configuration; the naming will be unified in a future release.

To achieve this, we're going to cover the following topics in this Use Case: 

• How to configure the Bot and Virtual User on the AI Workflow profile.
• How to prepare a reusable Authentication (API Key or OAuth 2.0 Client Credentials) so the bot can reach an authenticated external system.
• How to write a Flow Description — the playbook that tells the model when to call a tool, which one to pick, and what to do with the result.
• How to attach Web Requests and MCP Servers as Extension Tools, and how to describe them to the model.
• How to wire the Virtual User into a Nimbus Workflow, mapping its exits and the default exits (Fallback, Failed, Idle Timeout).

Preconditions

Use Case Overview

Details will be covered below in this Use Case. As a quick tl;dr, here is an overview of items you will need: 

Step 1 - Nimbus AI Bot Setup

Configuring the Bot

✅ The Bot is your “mapping” to the AI service that hosts the conversation.

1. Head to Nimbus Administration > Configuration > Bots and create a new Bot.
2. Give your Bot a descriptive name. 
   💡This name is just for Nimbus UI purposes.
3. Define the Organization Unit under which this Bot will be selectable. 
4. Type: pick Nimbus AI Service for the Luware-managed option (no endpoint or API key required), or Custom AI Service if you bring your own Azure OpenAI deployment.
5. Agent Type is Azure OpenAI (shown as “Azure OpenAI – GPT Realtime”) — the only agent technology that supports Web Requests and MCP Servers.
   💡If you picked Custom AI Service, fill in the Endpoint, Authentication Type and API Key fields. For Nimbus AI Service those fields are hidden — Nimbus provides them.
6. Save and Close.

Preparing the Authentication (for authenticated external systems)

✅ Most external systems (a CRM, a ticketing API, an internal MCP server) require credentials. Define them once as a reusable Authentication so both Web Requests and the MCP Server can reference the same item.

1. Head to Nimbus Administration > Configuration > Authentication and create a new item.
2. Give it a Name and Description, and set the Organization Unit in the same place (or higher) as your Virtual User.
   💡Set the OU to the same unit as your Virtual User (or a parent) — the MCP Server dropdown only lists Authentications from the Virtual User's OU and its parents.
3. Pick a Type:
   1. API Key — provide the API Key Name, How Sent (Request Header or Query String) and Key Value.
   2. OAuth 2.0 Client Credentials — provide the Access Token URL, Client ID, Client Secret and optional Scope. Nimbus then requests and refreshes the bearer token automatically.
   3. Basic Authentication — on which you provide username and password.
4. Save and Close. You can reuse this Authentication on any Web Request and on the Virtual User's MCP Server.

Configuring the Virtual User

✅ Virtual Users. Here you give your AI bot instructions on how to interact with the Customer, which Outcomes it can detect, and which Extension Tools it may use.

General tab

1. Head to Nimbus Administration > Configuration > Virtual Users and create a new Virtual User.
2. Give your Virtual User a descriptive name, e.g. Order Status Concierge.
   💡This name is just for Nimbus UI purposes, e.g. for later selection in your Workflows.
3. Define the Organization Unit under which this Virtual User is selectable. 
   💡Should ideally match the Services and Workflows accessing this Virtual User, and the OU where your Web Requests and Authentications live.
4. Optionally add a Description for internal identification (max. 256 characters). It has no impact on bot behavior.
5. Under Bot Configuration, Select the Bot you configured above.
6. Set Profile to AI Workflow.
   💡The Profile decides how the bot behaves in the conversation. For example: 
   1. Selecting AI Workflow unlocks the “Extension Tools” section on the Tools & Outcomes tab (Web Requests, MCP Servers, Flow Description). 
   2. The Open Profile profile does the same, but adds controls over Role, Verbosity and Tone. 
   3. The Intent Analyzer profile is intentionally blocked from using Extension Tools — pick it only for pure intent classification (see Use Case - Setting up a Nimbus Virtual User for Intent Analysis).

Behavior tab

1. The “System Instruction” field is your behavioral guideline (persona, hard rules, flow order). Keep it about who the bot is, not about which tool to call — the latter goes into the Flow Description below.
2. Define the Timeout behavior for your bot (in seconds). You have the following values to specify: 
   1. Max Session Duration (seconds): Maximum total duration the Virtual User stays in the call.
   2. Inactivity Timeout (seconds): How long the bot waits for caller input before taking the Idle Timeout exit.

Conversations tab

1. Optionally define the Initial Message to Customer:
   💡Note that the underlying AI will engage with the Customer automatically. You can use these instructions to lead directly into the first conversation topic / intent. By adding Custom Parameters or System Fields and Parameters (retrieved via CRM using Flow Actions) you can also lead directly into a more personal conversation. 
2. Optionally set a Final Message to Customer — a short line the Virtual User will say before handing off or disconnecting (e.g. “Thank you, I'll transfer you to a colleague now.”).
3. Define the Language and Virtual User Voice of your Virtual User.
4. On the Open Profile, you can additionally tune Verbosity, Tone (max. 200 characters) and Role (Deprecated). The Role field is being phased out and will be merged into the System Instruction in a future release — prefer putting persona guidance there.

Finalizing

1. Ensure your Virtual User has a license applied, If you want to use your Virtual User productively.  This license can be applied directly in the Virtual User configuration or — in bulk — via Admin > Licensing view.
   ⮑ Applying the license enables usage of the “Add Virtual User” Workflow Activity. When unlicensed, the activity will be skipped over.

Step 2 - Configuring Tools and Outcomes

By deciding to identify customer intent, and which external systems (tools) the Virtual User may reach into to retrieve data during the customer interaction. By describing both intents and tools well enough in your Flow Description, the bot knows which how to orchestrate the whole conversation effectively.

Outcomes

💡Outcomes (found on the Tools & Outcomes tab) let you list all the different results the bot can detect. You can also think of these as “Customer” intents, but also potential error or escalations, such as “I want to speak to a person”.
💡Note: the terms “Intent” and “Outcome” are used interchangeably in the Virtual User configuration; the naming will be unified in a future release.

✅For each intent you need to provide:

1. A mandatory, unique Name (keep it to one word, e.g. order_found, so the model detects it reliably) — this is the label you map to a Workflow exit later.
2. A mandatory Description telling the bot when to assign the intent (e.g. “The order was located and the status read back to the caller”).
3. The type — an exit intent (ends the session and can be mapped to a Workflow exit) or a non-exit intent (in-conversation only, e.g. parameter capture).
4. Optionally up to 10 Parameters the AI can fill with data collected during the conversation.

💡Good to know: MCP Server and Web Requests are independent checkboxes and both optional — your Virtual User can run with neither, either, or both. In either case, if you use them, make sure that you reference the used extensions in your flow description.

Flow Description

The Flow Description is a single free-text field on the Virtual User that tells the model how to drive the conversation when Extension Tools are involved. The model reads it alongside the System Instruction every turn and uses it to decide when to call a tool, which tool to pick, and what to do with the result. Note that the same Flow Description applies to both Web Requests and MCP Servers.

💡 Keep it concrete and step-driven. The model performs best when it can read the description as a numbered playbook rather than as prose:

• Spell out the conversation phases (greet → identify → look up → confirm → close).
• Don't duplicate the System Instructions (role, tone, language) in the tools. The Flow Description is about data and interaction flow, not personality.
• Avoid ambiguity by naming each tool by its exact label as defined in your Virtual User — “call the OrderLookup Web Request”, not “call the order system”.
• State when the bot should call a tool, and what to do if the tool fails or returns nothing.
• Keep the field length cap of 5,000 characters in mind.

Example for an order-status bot:

1. Greet the caller and ask for their order number.
2. Call the OrderLookup Web Request with the order number the caller provided.
3. If OrderLookup returns a result, read back the order status and the expected delivery date.
4. If OrderLookup returns no result or an error, apologise, offer to transfer to a human agent,
   and end the conversation.
5. After confirming the status, ask whether there is anything else. If not, say goodbye and close.

Never invent an order status. Only state what OrderLookup returns.

Attaching Web Requests

✅A Web Request attaches a (previously configured) Web Request definition item to the Virtual User so the model can call it mid-conversation.

1. Enable “Web Requests” on the Virtual User. This unlocks the Web Requests sub-section.
2. Click Create and pick a Web Request from the Virtual User's Organization Unit (or a parent OU). The Web Request's Name is what the model sees as the tool's identifier — use the same name in your Flow Description.
   💡The external HTTP API behind the Web Request can be secured with a reusable Authentication (API Key or OAuth 2.0 Client Credentials). This is configured on the Web Request itself, not on this binding.
3. Fill in the AI Description for this binding. This is a per-Virtual-User field — the same Web Request can have a different AI Description on every Virtual User it is bound to.

Attaching MCP Servers

An MCP Server attaches a Model Context Protocol endpoint to the Virtual User. The server's tools are exposed to the model in real time during the call.

1. Enable “MCP Servers” on the Virtual User. At least one MCP Server is required when the toggle is on.
2. Click “Create” and fill in: 
   1. Name of the MCP Server (must be unique on the Virtual User — use the same label in the Flow Description)
   2. URL (the server's SSE endpoint, e.g. https://jira.example.com/mcp/sse)
   3. Description
   4. Authentication — select a reusable Authentication instead of typing a header name and key inline.

Step 3 - Configuring your Nimbus Workflow

✅Last but not least you need to configure a new Workflows to handle the Audio/Video interaction between Customers and your new Virtual User.

1. Head to Nimbus Administration > Configuration > Workflows.
2. Design or adjust any existing workflows you want to repurpose. 
   💡We recommend creating a copy of an existing Workflow so you can switch and test it with ease and return back should something not work as intended.
3. In your Workflow, Accept a call as normally. 
   💡Important: Do NOT add a “Queue” activity unless you want to involve human interaction in your workflow as well (e.g. after the Virtual User interaction).
4. Connect your Caller to the AI by using the “Add Virtual User” activity. You can find it in the Conversation Handling Activities. 
5. Configure the “Add Virtual User” activity as follows:
   1. Virtual User: Select the Virtual User you configured above.
      💡Note that the AI will automatically greet the Customer with the “Initial Message to Customer” field instructions provided in the Virtual Users > Conversations tab. If any Parameters have been retrieved earlier in the workflow, they will be part of that message as well.
      💡When using the Workflow for Outbound Call: The Initial Message to Customer is spoken once the call connects.
   2. Map your exit Intents (Outcomes) to Workflow exits. Each exit intent you defined on the Virtual User appears here and can be wired to its own downstream path. At least one exit intent must be mapped before the activity can be saved; duplicate mappings are blocked, and an exit intent that is in use cannot be deleted on the Virtual User.
   3. Define a Fallback Parameter which receives the AI's summary of the conversation when the bot cannot resolve the request.
      💡If the bot detects none of your exit intents, the activity takes the Fallback exit.
      💡A good way to route this exit is a regular “Queue” step, so a human can take the call instead of the Virtual User. 
      💡The Parameter can also be shown in the Extensions Service Settings (e.g. within My Sessions) as additional context for the receiving service user.
6. Route all your mapped custom exits as well as the default exits of the activity (AI Fallback, Failed, Idle Timeout).
7. Finally: add the “Disconnect” activity at the end and Save your Workflow.

Testing your Virtual User

✅On any change we recommend thorough testing of your Virtual User.

1. As a reminder: Ensure your Virtual Users used in workflows have a license applied. Otherwise a warning is shown in your “Add Virtual User” workflow activity and it will not connect.
2. Apply the workflow in the Modalities Settings tab of your service.
3. Start a “Test Call” to your Service, either via PSTN or the UPN shown in the General Service Settings.
4. Test the tool-calling behaviour: 
   1. Try happy-path scenarios where the bot should call a specific Web Request or MCP Server.
   2. Try failure scenarios — caller gives wrong inputs, requests data your tools cannot provide — and verify the bot follows the fallback rules in your Flow Description rather than inventing answers.
   3. Verify the Outcome mapping: confirm each conversation outcome ends on the Workflow exit you mapped it to, and that an unresolved call leaves through the Fallback exit.
   4. If the bot picks the wrong tool, calls it at the wrong moment, or misuses its output, sharpen the Flow Description and the AI Description on the Tool Extension before changing the tools themselves.

Known Limitations