> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/assistance/the-assistant/connections/connect-your-own-ai-service.md).

# Connect your own AI service

Connect your company's own search or retrieval service as a source the AI Assistant can draw on, with each user verified through Microsoft Entra ID.

You can connect your company's own internal service as another source the AI Assistant[^1] can draw on, alongside your published Userlane content. When a user asks a question, the Assistant can pull relevant material from your service and cite it in the answer. Each user is verified through their existing Microsoft session, so your service applies its own access rules and returns only what that user is allowed to see.

This article covers what you need, how to set up the connection, and the request and response format your service has to follow. For knowledge base integrations such as SharePoint or Confluence, which are set up separately, see [Knowledge connectors](/assistance/the-assistant/connections/knowledge-connectors.md).

{% hint style="warning" %}
**Before starting.** You need two things:

* **A search or retrieval service of your own.** It takes a question and returns relevant content for it, rather than writing its own final answer.
* **A Microsoft Entra ID tenant,** so the Assistant can verify each user through their Microsoft session. Your Entra ID administrator grants Userlane delegated access to the service once. Without this consent, sign-in fails.
  {% endhint %}

## Set up the connection

{% stepper %}
{% step %}

#### Open the Connections tab

In the portal, under **Agentic Assistance**, open the **Connections** tab.
{% endstep %}

{% step %}

#### Enter the Microsoft tenant details

Under **Microsoft tenant**, enter your **Directory (tenant) ID** and **Application (client) ID**. These are shared by every application in your company.
{% endstep %}

{% step %}

#### Enter the AI service details

Under **AI service**, enter a name for the service and its endpoint. This is set per application, so different applications can point at different services.
{% endstep %}

{% step %}

#### Grant admin consent

Ask your Entra ID administrator to grant the one-time admin consent, so the Assistant can sign users in to your service.
{% endstep %}

{% step %}

#### Check the request and response format

The page shows the request and response format your service has to follow, described in the next section. There is nothing to configure there. It is shown for whoever builds your service.
{% endstep %}

{% step %}

#### Save the connection

Save your changes.
{% endstep %}
{% endstepper %}

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FfUYVro4x0aTDUcwkAmz2%2Fconn-tenant.png?alt=media" alt="The Connections tab under Agentic Assistance with the Microsoft tenant fields"><figcaption><p>Microsoft tenant details on the Connections tab.</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FT0sLRitbONCG8dbJSBko%2Fconn-service.png?alt=media" alt="The AI service section of the Connections tab with the service name and endpoint fields"><figcaption><p>The AI service name and endpoint.</p></figcaption></figure></div>

{% hint style="success" %}
**Result.** When a user asks a question, the Assistant can query your service alongside your Userlane content and cite what it uses.
{% endhint %}

## Request and response format

The Assistant sends your service the user's question and expects a list of results in return. Each result carries an `id`, a `title`, a `url`, and a short `snippet` of the relevant content. The exact format is also shown in the portal.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2F6EjikbVNn5xhQdkl3ykY%2Fconn-format.png?alt=media" alt="The request and response format shown on the Connections tab"><figcaption><p>The request and response format as shown in the portal.</p></figcaption></figure></div>

### Request

```http
POST /v1/search
{
  "version": 1,
  "query": { "question": "How do I reset the password on my finance account?" }
}
```

### Response

```json
{
  "version": 1,
  "results": [
    {
      "id": "kb-4471",
      "title": "Reset your password",
      "url": "https://help.example.com/kb/4471",
      "snippet": "To reset your password, open Settings, choose Security, then..."
    }
  ]
}
```

## How access is checked

Because each user is verified through their existing Microsoft session, your service returns only content that user already has access to, and the Assistant cites what it uses. This differs from the SharePoint knowledge connector, which reads with the permissions of a registered application rather than those of the person asking.

Your connected service adds to your Userlane content. It does not replace it.

## Troubleshooting

<table><thead><tr><th width="200">Problem</th><th width="240">Likely cause</th><th>What to do</th></tr></thead><tbody><tr><td>Users cannot sign in to the service</td><td>The one-time admin consent has not been granted in Microsoft Entra ID</td><td>Ask your Entra ID administrator to grant the admin consent</td></tr></tbody></table>

## Relevant articles

{% content-ref url="/pages/XDGntxUJimFOtJOihyow" %}
[The Assistant](/assistance/the-assistant.md)
{% endcontent-ref %}

{% content-ref url="/pages/jaGpQWjETS3dwv2yneLk" %}
[Configure the AI Assistant](/assistance/the-assistant/configure-the-ai-assistant.md)
{% endcontent-ref %}

{% content-ref url="/pages/FxcQeBasWlRhc3HVdmJT" %}
[Knowledge connectors](/assistance/the-assistant/connections/knowledge-connectors.md)
{% endcontent-ref %}

{% content-ref url="/pages/14ViydxzHwBkmZMnQj6h" %}
[AI features: what data is processed and where](/security-and-privacy/ai-features-what-data-is-processed-and-where.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>Can a service that writes its own answers be connected?</summary>

No. The service has to return a list of results, each with an id, a title, a url, and a snippet. The Assistant writes the answer and cites the results.

</details>

<details>

<summary>Does a connected service replace Userlane content?</summary>

No. The Assistant draws on your connected service alongside your Userlane content.

</details>

<details>

<summary>Can the Assistant show a user content they are not allowed to see?</summary>

No. Each user is verified through their Microsoft session, so your service returns only content that user already has access to.

</details>

<details>

<summary>Is the connection set per company or per application?</summary>

Both. The Microsoft tenant details are shared by every application in your company. The service name and endpoint are set per application.

</details>

[^1]: The AI Assistant is the conversational feature inside the Userlane Assistant panel that answers questions from published and connected content, and hands off to guides or support.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/assistance/the-assistant/connections/connect-your-own-ai-service.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.