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 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 outcome, the Virtual User now returns a conversation result through these Intents you define on the Virtual User and then map to Workflow exits.

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 exit Intents 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 (Intents) it can detect, and which Extension Tools it may use.

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. Select the Bot you configured above.
5. Set Profile to AI Workflow.
   💡The Profile decides how the bot behaves in the conversation. AI Workflow unlocks the Extension Tools section further down the page (Web Requests, MCP Servers, Flow Description). The Open Profile profile behaves the same as AI Workflow for Extension Tools, but adds controls over Role, Verbosity and Tone. The Intent Analyzer profile is intentionally blocked from using Extension Tools — pick it only for pure intent classification (see the Intent Analysis use case).
6. The “System Instructions” 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.
7. Optionally define the Initial Message:
   💡Note that this field is optional in Nimbus: The underlying AI will engage with the Customer automatically. Optionally 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 direct conversation. 
8. Optionally set a Closing Message — 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.”).
9. Define the Language and Voice of your Virtual User.
10. Define the Timeout behavior for your bot (in seconds). You have the following values to specifcy: 
    1. Session Timeout: Maximum total duration the Virtual User stays in the call.
    2. Idle Timeout: How long the bot waits for caller input before taking the Idle Timeout exit.
11. 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 unlincensed, the activity will be skipped over.

Step 2 - Configuring Tools and Intents

This is the heart of the integration: deciding how 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.

Intents

💡Intents allows you to list the all the different outcomes the bot can detect. You can also think of this as “Customer” intents, but also potential error or escalations, such as “I want to speak to a person”.

✅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 Virtual User will greet the Customer with the “Initial Message” field instructions provided. If any Parameters have been retrieved earlier in the workflow, they will be part of that message as well.
      💡Outbound calls: when the “Add Virtual User” activity runs inside an outbound-call workflow, the Initial Message is spoken once the call connects — no extra silence before the greeting.
   2. Map your exit Intents 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.
      💡This replaces the previous single fixed Success exit. Existing Workflows keep working — their prior Success exit is carried across automatically.
   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 (there is no longer an implicit default Success).
      💡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 the mapped exit Intents and the default exits of the activity (AI Fallback, Failed, Idle Timeout).
7. Finally: add the “Disconnect” activity at the end and Save your Workflow.

Known Limitations