> ## Documentation Index
> Fetch the complete documentation index at: https://help.agentsy.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect and configure your AI

> Use the Agentsy AI Experience Builder, connect an OpenAI or xAI API key, and link your provider-hosted knowledge store to Agentsy.

Agentsy gives your expertise a branded, interactive website. **You don't create a separate AI assistant inside Agentsy.** Instead, you configure an AI Experience that uses an AI model and knowledge resources from your chosen provider.

This guide shows how to bring three things together:

1. **System Instructions** generated with the [Agentsy AI Experience Builder](https://www.agentsy.pro/build-your-ai).
2. **A model selection** for the AI that will power your experience.
3. **An API key** created in your OpenAI or xAI developer account.
4. **A knowledge-store ID** from the same provider, after you upload your documents there.

> [!NOTE]
>
> You can use ChatGPT, Claude, Grok, or another preferred AI to work through the **Builder prompts**. That is separate from the provider you select to power your live Agentsy experience. This guide covers connecting **OpenAI or xAI (Grok)** to Agentsy.

## 1. Generate your System Instructions

Open [Build Your AI](https://www.agentsy.pro/build-your-ai) and follow the **AI Experience Builder** step.

1. Copy the Builder prompt into your preferred AI chat.
2. Work through the conversation. The AI can use context it already knows about your work and ask for clarification when needed.
3. Review the resulting **System Instructions** and **Knowledge Sources Checklist**.
4. Keep the System Instructions ready to paste into Agentsy.

You do **not** need to write a production prompt from scratch or collect every document before starting. The Builder helps you identify what knowledge would be useful.

> [!TIP]
>
> The Builder also offers an **Experience Page Builder** to help prepare your website messaging and branding. You can apply those outputs when customizing your Agentsy website.

## 2. Open your AI Experience settings in Agentsy

1. Sign in to your Agentsy workspace.
2. Open the AI Experience you want to configure.
3. Navigate to **Settings → AI Experience** (or the corresponding AI Experience settings tab in your workspace).
4. Locate the fields for **Model**, **System Instructions**, **API Key**, and **Vector Store ID**.

Paste the Builder-generated **System Instructions** into the **System Instructions** field and save your changes when prompted.

> [!NOTE]
>
> The field name **Vector Store ID** is used in Agentsy even when your provider uses a different name for its document collection.

## 3. Select your AI model

In the **AI Experience** settings tab, find the **Model** field and choose the model that will power conversations on your branded website.

**The current default model is `gpt-5.5`.** If you want to use the default, confirm that it is selected. You can choose another model from the options supported by your Agentsy workspace.

Before continuing:

1. Check which provider supplies the selected model (for example, OpenAI or xAI).
2. Make sure you have API access to that model through the provider.
3. Use an API key from the **same provider** as the model you selected.
4. If you are connecting a knowledge store, use a compatible store from that provider as well.

> [!TIP]
>
> If you are setting up your first experience, start with the default **`gpt-5.5`** model unless you have a specific reason to choose another supported option. You can review your model selection later as you test answer quality, speed, and provider costs.

> [!NOTE]
>
> Model availability and pricing depend on your provider and API account. Selecting a model in Agentsy does not automatically grant access to it.

## 4. Create an API key with your AI provider

Select the provider you intend to use for the live experience. The key must come from **that provider's developer/API platform**, not from a regular chat conversation.

### OpenAI

1. Visit the [OpenAI API platform](https://platform.openai.com/).
2. Sign in or create an API platform account and review any required billing setup.
3. Create an API key in your project or API-key settings.
4. Copy the key securely.
5. Return to Agentsy and paste it into the **API Key** field for your OpenAI configuration.

### xAI (Grok)

1. Visit the [xAI Console](https://console.x.ai/).
2. Sign in and review the available API access and billing requirements.
3. Create an **xAI API key** with the permissions needed for inference and document search.
4. Copy the key securely.
5. Return to Agentsy and paste it into the **API Key** field for your xAI configuration.

> [!WARNING]
>
> **Treat API keys as secrets.** Do not place them in your System Instructions, knowledge documents, website text, screenshots, or public GitHub repositories. Paste them only into the designated secure configuration field. If a key is exposed, revoke or rotate it through the provider.

An API subscription is separate from a consumer ChatGPT or Grok chat subscription. Provider API usage may incur charges under the provider's terms.

## 5. Create your knowledge store and upload documents

Your **Knowledge Sources Checklist** tells you which documents to prepare. The actual files must be uploaded to the **selected provider's knowledge-storage service**, not merely listed in the Builder's output.

| Provider | Provider's name for the knowledge store | ID to use in Agentsy |
| - | - | - |
| **OpenAI** | **Vector store** | **Vector store ID** |
| **xAI (Grok)** | **Collection** | **Collection ID** |

### OpenAI: create a vector store

1. Open the [OpenAI API platform](https://platform.openai.com/).
2. Find the vector-store or file-search management area for your project.
3. Create a vector store for your AI Experience.
4. Upload your approved documents and add them to that vector store.
5. Wait for file processing to finish and check that the documents are available.
6. Copy the **vector store ID**, not an individual file ID.
7. Paste it into the **Vector Store ID** field in Agentsy.

See the [OpenAI File Search documentation](https://platform.openai.com/docs/guides/tools-file-search) for current provider instructions.

### xAI (Grok): create a Collection

xAI calls its persistent, searchable document store a **Collection**. It is the counterpart to an OpenAI vector store for this setup.

1. Open the [xAI Console](https://console.x.ai/).
2. Find **Collections** and create a collection for your AI Experience.
3. Enable document indexing or embeddings where the Console offers that option.
4. Upload your approved files and add them to the collection.
5. Confirm the documents are processed and searchable.
6. Copy the **Collection ID**, not an individual document or file ID.
7. Paste the **Collection ID** into Agentsy's **Vector Store ID** field for the xAI configuration.

See [xAI's Collections guide](https://docs.x.ai/developers/files/collections) and [Console walkthrough](https://docs.x.ai/console/collections) for current instructions.

> [!WARNING]
>
> **Use a matching provider and resource.** An OpenAI API key should be paired with an OpenAI vector store ID; an xAI API key should be paired with an xAI Collection ID. Do not interchange their IDs. If Agentsy rejects an xAI Collection ID, confirm that your selected provider and current Agentsy configuration support Collections before proceeding.

## 6. Review and save the configuration

In **Settings → AI Experience**, confirm that the following values are present and belong to the same intended experience:

| Agentsy setting | What to enter |
| - | - |
| **Model** | Your selected supported model; currently **`gpt-5.5`** by default |
| **System Instructions** | The reviewed output from the AI Experience Builder |
| **API Key** | Your secret key from the selected provider |
| **Vector Store ID** | OpenAI vector store ID **or** xAI Collection ID |

Save the settings. If you change providers later, review the model, API key, and knowledge-store ID together; switching only one field can break responses or retrieval.

## 7. Test your AI Experience

Open your AI Experience as a visitor and try these checks:

* **Basic response:** Ask what the experience helps people understand.
* **Knowledge retrieval:** Ask a question that should be answered from one of your uploaded documents.
* **Missing information:** Ask something your knowledge does not cover. The AI should acknowledge uncertainty rather than invent an answer.
* **Human handoff:** Express interest in speaking with the expert or taking the next step.
* **Visitor access:** Check the intended public, registered, or invite-only experience.

If the assistant responds but cannot answer questions from your documents, check the **Vector Store ID / Collection ID**, file processing status, provider selection, and API permissions before rewriting your System Instructions.

See [Testing your assistant](/create-and-configure/testing-your-assistant) and [Knowledge retrieval problems](/troubleshooting-and-support/knowledge-retrieval-problems).

## Common setup problems

| Symptom | What to check |
| - | - |
| Authentication or API error | Correct provider, valid API key, selected model access, permissions, and provider billing status |
| Model unavailable or unsupported | Check that the selected model is offered in Agentsy and accessible with your provider API key |
| Assistant responds without using documents | Correct knowledge-store ID, completed document processing, and supported retrieval configuration |
| Knowledge store cannot be found | You copied a **file ID** instead of the OpenAI **vector store ID** or xAI **Collection ID** |
| Instructions aren't followed | The current System Instructions were saved in the correct AI Experience |
| OpenAI works but xAI does not (or vice versa) | The selected model, API key, and knowledge-store ID all belong to the same provider |

> [!NOTE]
>
> Some provider capabilities, models, and account requirements change over time. Always consult the provider's current documentation if a screen or label differs from this guide.

## Setup checklist

* [ ] Generate and review System Instructions with the AI Experience Builder.
* [ ] Paste the instructions into **Settings → AI Experience** in Agentsy.
* [ ] Select the model to use (currently **`gpt-5.5`** by default) and confirm API access.
* [ ] Create an API key in OpenAI or xAI and enter it in the **API Key** field.
* [ ] Create an OpenAI vector store or xAI Collection.
* [ ] Upload and process the actual knowledge files at the provider.
* [ ] Paste the correct store or collection ID into Agentsy's **Vector Store ID** field.
* [ ] Test ordinary questions, knowledge retrieval, boundaries, and human handoff.

## Next steps

Once your AI configuration works, customize the branded website with the outputs from the **Experience Page Builder** and test the visitor journey before sharing it.

* [Customize your AI website](/branding-and-website/customize-your-ai-website)
* [Public and private access](/create-and-configure/public-and-private-access)
* [Publish your AI Experience](/share-and-grow/publish-your-ai-experience)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.