> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/admin/apis-and-integrations/ai-assistant.md). # AI Assistant The Welkin AI integration connects each Welkin instance to an external AI provider so that AI-powered features — such as AI-generated patient summaries in the Care Portal — are available to care team members. *** ## Prerequisites Before configuring Welkin AI, confirm that the **Welkin AI** license is enabled for your organization. Contact your Welkin Implementation Manager or CSM if you are unsure. *** ## Accessing the Welkin AI Configuration 1. Log in to the **Admin Portal**. 2. Navigate to **Integrations → Welkin AI**. 3. A card is shown for each instance in your organization. *** ## Configuring an Instance Each instance must be configured separately. 1. Click the **edit (pencil) icon** on the instance card. 2. A configuration drawer opens with the following fields: | Field | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API Key** | The API key issued by your AI provider. Required. | | **Provider** | Select the AI provider from the available list. Required. | | **Model** | Select the model offered by the chosen provider. Required. The model list updates when you change the provider. Deprecated models are shown but cannot be selected for new configurations. | | **Key Origin** | Read-only. Indicates whose API key is stored: **CUSTOMER** (your organization's key) or **PLATFORM** (a Welkin-managed key). Defaults to **CUSTOMER** for all standard configurations. This value updates automatically if the API key is replaced. | 3. Click **Save** to apply the configuration. Welkin validates the API key against the selected provider when you save. If the key is invalid or cannot be reached, the save will fail with an error — correct the key before retrying. After saving, the card displays the masked API key, provider name, model, and key origin. ### Available Models | Provider | Model | Notes | | ------------- | ---------------- | ---------------------------------------------------------- | | **OpenAI** | GPT-5.6 Terra | Standard workhorse model | | **OpenAI** | GPT-5.6 Luna | Cost-optimized tier | | **Anthropic** | Claude Sonnet 5 | Primary Anthropic model; near-Opus quality at Sonnet price | | **Anthropic** | Claude Opus 5 | Premium Anthropic model | | **Anthropic** | Claude Haiku 4.5 | Lightweight Anthropic model | > **Note for existing configurations:** If your instance was previously configured with an older model (GPT-5.4, GPT-5.4 Mini, GPT-5.4 Nano, Claude Sonnet 4.6, or Claude Opus 4.6), it has been automatically migrated to the closest current equivalent. No action is required — your AI features will continue to work. *** ## Speech-to-Text (STT) Configuration If your organization has the voice/STT add-on enabled, you can configure a speech-to-text provider for each instance. The STT provider is used to transcribe audio recordings submitted via the audio transcription feature. The STT configuration fields are: | Field | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------- | | **STT Provider** | Select the speech-to-text provider (e.g., OpenAI). Must be set if an STT API Key is provided. | | **STT Model** | The transcription model to use (e.g., `whisper-1`). Optional — defaults to the provider's standard model if left blank. | | **STT API Key** | The API key for the STT provider. Required when an STT Provider is selected. | > **Validation rules:** The STT Provider and STT API Key must either both be set or both be left blank. Saving a configuration with a provider but no API key, or an API key but no provider, returns a `STT_CONFIG_INCOMPLETE` validation error. Welkin also validates the STT API key against the provider at save time — an invalid key will prevent the configuration from being saved. > **Removing the STT configuration:** To remove a previously saved STT block and return the instance to the chat-provider fallback, clear both the STT Provider and STT API Key fields and save. You can also send `"stt": null` via the API PATCH endpoint to clear the STT block. > **Chat provider fallback:** If no STT block is configured, Welkin automatically uses the chat provider's speech-to-text service when one is available (for example, an OpenAI chat configuration will fall back to OpenAI Whisper). Providers that do not offer a speech-to-text API (such as Anthropic) have no fallback — audio transcription will return a service unavailable error until an explicit STT block is configured. *** ## AI Assessment Drafting The AI Assistant can pre-fill a patient assessment on the care team member's behalf, based on answers dictated during a chat conversation. This is a care-team-facing workflow — see [AI Assessment Drafting](https://docs.welkinhealth.com/care/ai-assistant/ai-assessment-drafting) in the Care documentation for how it works, draft modes, and what the assistant will and won't fill in. *** ## Updating a Configuration 1. Click the **edit icon** on the instance card. 2. Modify any field and click **Save**. > **Key Origin behavior when updating:** If you replace the API key without specifying a different Key Origin, the Key Origin resets to **CUSTOMER**. The Key Origin always follows the key — swapping in your own key marks the config as customer-owned. *** ## Deleting a Configuration 1. Click the **trash icon** on the instance card. 2. A confirmation prompt appears: **"Delete this Welkin AI config?"** Click **Yes, Delete** to confirm, or **No, Keep it** to cancel. After deletion, the AI features powered by this instance will no longer function until a new configuration is saved. *** ## AI Turn Audit Welkin records a detailed log entry (called a **turn**) for every AI interaction — both chat messages and one-shot completions such as patient summaries. The turn audit lets administrators and support staff answer questions like "What did the AI see when it generated this summary?" and "Which turn produced a specific response?" without needing direct database access. ### Searching Turns The turn audit search supports the following filters: | Filter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Status** | Filter by outcome: `SUCCESS`, `ERROR`, or other terminal states. | | **From / To** | Date range for when turns were created. | | **User ID** | Limit results to turns initiated by a specific care team member. | | **Error Code** | Filter by a specific error code (e.g., `TOOL_LIMIT_EXCEEDED`). | | **Request ID** | Find the exact turn associated with a specific request. The request ID is the trace identifier that flows across the entire call chain (frontend → Welkin backend → AI assistant). Use this when a support report or dataview complaint arrives with a trace ID. | ### Turn Detail Opening a turn's detail view shows: * **System prompt** — the full prompt sent to the AI model before the turn ran. For chat turns this includes the live patient data overview; for one-shot summary turns it contains the task template and tenant-editable instructions. * **User text** — the exact message the model received. For summary turns this differs from the stored question (which holds the tenant instructions), as it includes the summary trigger text and any focus record references. * **Trace** — low-level execution detail including the effective model, provider, key origin, and temperature used for the turn. * **Tool calls** — the sequence of tool calls the model made and their results. * **Answer** — the text the model produced. > The system prompt and user text are captured before the model runs, so a turn that fails mid-stream still shows what the model was given. ### Tool-Call Limit One-shot completion turns (e.g., patient summaries) enforce a maximum of **15 tool calls per turn**. If the model exceeds this limit, the turn finalizes with the status `TOOL_LIMIT_EXCEEDED` rather than running indefinitely. Chat turns have a separately configured limit. ### Prompt Snapshot Setting The system prompt and user text capture is controlled by the `welikan.ai-assistant.audit.prompt-snapshot` configuration flag, which is **on by default**. Disabling it stops new prompt text from being written to turn rows but does not delete existing records. Contact Welkin support if you need to adjust this setting. *** ## Related Topics * [Admin Portal Overview](/admin/admin.md) * [How to Turn On Communication Methods](/admin/apis-and-integrations/communication-center-how-to-turn-on-your-communication-methods.md) * [AI Assistant (Care)](https://docs.welkinhealth.com/care/ai-assistant) — the care team member's chat panel and assessment-drafting workflow --- # 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.welkinhealth.com/admin/apis-and-integrations/ai-assistant.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.