Connect an AI Provider
Before anyone can chat with an assistant, the site needs to reach an AI service, such as OpenAI or Azure OpenAI. An administrator does this once in three steps: add a connection with the service's address and key, add a deployment for each model you want to use, and choose the site's default models.
| Menu | Artificial Intelligence > Provider Connections; Artificial Intelligence > Deployments; Settings > Artificial Intelligence |
| Permission | Manage AI Provider Connections; Manage AI deployments; Manage AI profiles (for the settings) |
| Feature | AI Services and AI Connection Management, plus a provider feature: OpenAI Chat, Azure OpenAI Chat, Azure AI Inference Chat or Ollama AI Chat |
What you see depends on your role. If the menu, a button or a setting on this page is missing, ask your administrator to give you the permission listed above or to turn on the feature. Only administrators can turn features on and change site settings.
The video covers why the provider is set up once, how connections, deployments and default models fit together, and each task below.
Your technical team can also set up connections and deployments in the site's configuration files. Those show in the lists under Configuration-based connections or Configuration-based deployments with a Read-only badge, and can only be changed there. See the Technical Manual provider pages.
Add a connection
A connection holds the address and the key the site uses to reach one AI service account.
- Open Artificial Intelligence > Provider Connections and click Add Connection.
- In Available Providers, click Add on your provider.
- Fill in the fields below and click Save.
| Field | What it does |
|---|---|
| Title | The name shown for the connection. Required. |
| Technical name | A unique name, filled in from the title. It cannot be changed later. |
| Endpoint | The service's web address, from your provider's portal. OpenAI, Azure OpenAI and Azure AI Inference only. |
| Authentication type | Azure OpenAI and Azure AI Inference only. Default authentication, Managed identity or API key. Your technical team tells you which to use. |
| API key | The secret key from your provider. It is stored securely and never shown again. To keep a stored key, leave the field blank when you edit the connection. |
| Identity client ID | Managed identity only, and only when your team gives you one. |
Many AI services, such as DeepSeek, Google Gemini or Together AI, work like OpenAI. Choose OpenAI and enter that service's endpoint and key.
The site checks the fields when you click Save; it does not contact the provider. If the key or the address is wrong, you find out the first time someone chats. A change to a connection can make the site reload its settings for a moment.
Ollama connections only have a Title and a Technical name in the admin; the address of the Ollama server is set in the site's configuration by your technical team.
Add a deployment
A deployment is one model you use through a connection, such as gpt-4.1-mini for chat or text-embedding-3-small for search. Add one for every model the site needs.
- Open Artificial Intelligence > Deployments and click Add Deployment.
- In Available Providers, click Add on the provider of the model.
- Fill in the fields below and click Save.
| Field | What it does |
|---|---|
| Model name | The model or deployment name exactly as your provider knows it, for example gpt-4.1-mini. Required. |
| Technical name | A unique name used by profiles and settings, filled in from the model name. It cannot be changed later. |
| Connection name | The connection the model is used through. Picked for you when the provider has only one. |
| Model capabilities | What the model can do. See below. At least one is required. |
| Pricing | Optional. What the model costs, so the AI reports can show an estimated cost. See below. |
Model capabilities
Tick, under Trained features, only what the model really supports. The site uses these ticks to decide where the model is offered: an embedding model shows up only where an embedding model is needed, and a feature you leave unticked is never asked of the model.
| Capability | Tick it for |
|---|---|
| Text conversation | Models that answer chat messages. Ticked by default. |
| Tool calling | Chat models that can use tools. Ticked by default. |
| Streaming | Chat models that write the answer as it comes. Ticked by default. |
| Structured outputs | Chat models that can answer in a fixed format. |
| Reasoning | Models that think before answering. Ticking it shows Reasoning effort. |
| Text embedding | Embedding models used to search documents and knowledge bases. Never for a chat model. |
| Image input (vision) | Models that can read pictures. |
| Image output | Models that create pictures. |
| Speech to text (transcription) | Models that turn speech into text, such as Whisper. |
| Text to speech (synthesis) | Models that read text aloud. |
| Realtime (speech-to-speech) | Live voice models that hold spoken conversations. |
| Audio input, Audio output, Video input, Video output | Models that accept or produce audio or video directly. |
Reasoning effort lets profiles choose how hard a reasoning model thinks: Minimal, Low, Medium, High or Extra high. Tick it, then optionally narrow the Supported values to those your model accepts, and pick a Default value (it starts on Medium). Higher effort gives more careful answers but is slower and costs more.
Pricing
Set what your provider charges for the model, and the AI Usage Analytics report shows an estimated cost for its usage. You can skip it: a model without prices is reported without a cost.
- In Currency, type the currency your prices are in, such as
USD. - Click Add price and pick what the price is for, such as Input tokens.
- Type the price and pick the quantity it is for in per, such as 1M tokens.
- Repeat for each thing the provider charges for, then click Save.
Add one price for each thing the provider charges for. For example, a chat model gets Input tokens, Cached input tokens (cache reads) and Output tokens, a speech-to-text model gets Audio duration per minute or per hour, and a text-to-speech model gets Characters. A model that charges per request and per token gets both a Requests price and its token prices. Remove a price with its trash button.
| Price for | Use it when the provider charges for |
|---|---|
| Input tokens, Output tokens | The text the model reads and writes. |
| Cached input tokens (cache reads), Cache write tokens | Text served from, or written to, the provider's prompt cache. |
| Audio input tokens, Cached audio input tokens, Audio output tokens | Speech the model hears or speaks, for models that count audio in tokens. |
| Image input tokens, Image output tokens | Pictures the model reads or creates, for models that count images in tokens. |
| Audio duration | The length of the audio, per second, minute or hour. |
| Characters | The characters read aloud. |
| Images | Each picture created. |
| Requests | Each request. |
| Web searches, Web fetches | Web searches and page reads the provider makes for the model. |
| Other reported count | Any other count your provider reports. Type its name in Count name exactly as the usage report shows it. |
Click the sliders button of a price for two more options:
- Only above ... input tokens: the price applies only to requests with more input tokens than this, in place of the regular price. Use it for models that charge more for long requests.
- Round up to: each request is billed in steps of this size, such as
15seconds of audio.
The estimate uses your prices, not your bill. Your provider's discounts and credits are not in it.
Special deployments
- Azure AI Services deployments carry their own Endpoint, Authentication type and API key instead of a connection. Use one for Azure speech-to-text.
- A Cascaded Realtime deployment gives you spoken conversations when your provider has no live voice model. It chains three deployments you already have: a Speech-to-text deployment that hears the user, a Chat deployment that writes the reply, and a Text-to-speech deployment that speaks it. The speech-to-text deployment must also have Realtime (speech-to-speech) ticked, because it has to transcribe continuously. The three can come from different providers. Expect a little more delay before the assistant starts speaking than with a live voice model.
Choose the default models
Open Settings > Artificial Intelligence and fill in the Default Deployments section. A profile or chat left on Default uses these. Each list only shows deployments with the right capability.
| Field | What it is used for |
|---|---|
| Default chat deployment | Chats and chat interactions that do not pick a model. Set this one first. |
| Default utility deployment | Small side jobs, such as planning and working out what the user wants. |
| Default embedding deployment | Searching documents and knowledge bases. |
| Default image deployment | Creating pictures. |
| Default vision deployment | Reading pictures that users attach. |
| Default speech-to-text deployment | Dictation and spoken conversations. |
| Default text-to-speech deployment | Reading answers aloud and spoken conversations. |
| Default text-to-speech voice | The voice used when a profile does not pick one. The list loads after you pick a text-to-speech deployment. |
| Default realtime deployment | Spoken conversations, in the chat and on phone calls, of profiles that name no Conversation deployment. Left empty, the first realtime-capable deployment is used. |
Click Save.
Other site-wide AI settings
The video is a tour of every card of the page. Saving the page may restart the website for a moment.
The same page has these sections, each explained on its own page:
| Section | Where it is explained |
|---|---|
| General | Enable preemptive memory retrieval lets the assistant read a user's memory before it answers. Maximum iterations per request limits how many times the assistant may call tools to write one answer (never more than 100). Enable distributed caching lets the AI services cache answers on a shared cache, and Enable OpenTelemetry sends AI requests to your monitoring tool. See also the Technical Manual. |
| Default Orchestrator | Enable preemptive retrieval-augmented generation (RAG): search your knowledge before every answer. See Knowledge. |
| Prompt Security and Visitor Identity | Protections for public chat. See Chat widgets. |
| Data Sources and Documents | Defaults for Knowledge. |
| Chat Interactions | Voice and read-aloud for chat interactions. |
| Memory | Memory. |
| Admin Widget | The admin chat widget. |
| Copilot and Claude | Sign-in for the GitHub Copilot and Claude engines, set up by your technical team. See the Technical Manual pages for Copilot and Claude. |
| MCP Server | Which tools outside AI apps may use. See Tools and agents. |
| WebMCP | Which tools AI assistants in the browser, and the site's own chat, may use on the pages you open. See WebMCP. |
Where each model is used
| You want | You need a deployment with |
|---|---|
| Chat, chat widgets, AI workflow tasks | Text conversation |
| Answers from documents, data sources, file sources or web crawlers | Text embedding (for the search index) plus a chat model |
| Attach pictures in a chat, or describe figures in documents | Image input (vision) |
| Create pictures | Image output |
| Dictate messages | Speech to text (transcription) |
| Read answers aloud | Text to speech (synthesis) |
| Spoken conversations | Realtime (speech-to-speech), or a Cascaded Realtime deployment, or both a speech-to-text and a text-to-speech default |