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

# Create and configure an AI assistant

> Choose the knowledge an assistant answers from, the model it runs on and the guidance that shapes its replies, then activate, disable or archive it later.

An **assistant** is what answers questions. Each assistant has its own knowledge, model and guidance, so one organisation can run several: a public documentation assistant and an internal engineering assistant, for example, with different content and a different tone.

An assistant answers only from the collections attached to it, so the knowledge has to exist before the assistant is useful: [how your content becomes answerable](/knowledge/overview) covers collections, sources and ingestion end to end.

## Settings

| Setting         | API field            | What it does                                                                                                                       |
| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Name**        | `name`               | What your team calls the assistant. Up to 120 characters                                                                           |
| **Description** | `description`        | Optional. What the assistant is for. Up to 500 characters                                                                          |
| **Knowledge**   | `knowledge_base_ids` | The collections the assistant answers from. Up to 20                                                                               |
| **Model**       | `model`              | The model that writes answers. Omitted, it is `anthropic/claude-sonnet-5`, so set it when your deployment offers a different model |
| **Guidance**    | `instruction`        | How the assistant should behave and write. Up to 8,000 characters; longer text is cut                                              |
| **Status**      | `status`             | `active`, `disabled` or `archived`                                                                                                 |

Changes apply to the **next question**. There is nothing to restart or republish.

## Create an assistant

<Tabs>
  <Tab title="Console">
    1. Open **Assistants** and select **New assistant**.
    2. Enter a **Name**, and optionally a **Description**, **Model** and **Guidance**.
    3. Under **Knowledge**, tick the collections the assistant should answer from. When your organisation has exactly one collection, it is already ticked. A collection embedded with a different model from the ones you have ticked cannot be combined with them and is shown disabled, with the reason.
    4. Select **Create assistant**.

    To change an existing assistant's knowledge, select **Knowledge** on its row, change the ticked collections and select **Save knowledge**. The row shows **No knowledge attached** while an assistant has none.

    If your organisation has no collections yet, the dialog says so. [Connect a source](/knowledge/sources) first; the console creates a collection for it, which you can then attach.
  </Tab>

  <Tab title="API">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl --request POST "$MITHUNAI_URL/arukz/api/v1/assistants" \
      --header "Authorization: Bearer $MITHUNAI_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "name": "Docs assistant",
        "description": "Answers questions about our public documentation.",
        "knowledge_base_ids": ["<collection id>"],
        "instruction": "Answer for software engineers. Be concise and include code where it helps."
      }'
    ```

    To attach knowledge to an existing assistant, send `knowledge_base_ids` to [Update an assistant](/api-reference/assistants/update-assistant). The list you send replaces the current one.
  </Tab>
</Tabs>

<Warning>
  An assistant with no knowledge attached cannot answer. Questions to it are refused with `400
      validation_error` until at least one collection is attached.
</Warning>

## Choose a model

[List the model catalogue](/api-reference/models/list-models) to see which models your deployment can use, then set `model` to one of the returned `id` values. The catalogue lists only models whose provider your deployment is configured for.

The model changes how answers are written. It does not change what they are grounded in: every model answers from the same retrieved evidence.

## Write guidance

Guidance shapes tone, format, audience and framing. Good guidance is short and specific:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
You answer questions from developers integrating our payments API.
Prefer short answers with a code sample in the language the user asked about.
Refer to the product as "Acme Pay". Link to the relevant reference page when one is cited.
```

Guidance **cannot loosen grounding**. An instruction such as "answer from general knowledge when the docs don't cover it" has no effect: the platform checks every answer against the retrieved evidence, whatever the guidance says. See [How answers work](/concepts/how-answers-work).

## Lifecycle

| Status     | Answers questions | Use it to                                                                               |
| ---------- | ----------------- | --------------------------------------------------------------------------------------- |
| `active`   | Yes               | Serve users. New assistants start here                                                  |
| `disabled` | No                | Take an assistant offline temporarily                                                   |
| `archived` | No                | Retire an assistant you no longer need. It is left out of the MCP `list_knowledge` tool |

Assistants cannot be deleted. Archive an assistant you no longer need, and set `status` back to `active` to bring it back.

While an assistant is `disabled` or `archived`, its conversations still appear in [List conversations](/api-reference/conversations/list-conversations), but every other request about one of them (reading, renaming, archiving or deleting it, listing its messages, or asking in it) returns `400`. The same applies to a widget embed that uses the assistant. Set the assistant back to `active` to use them again.

## Who can configure assistants

Owners, Administrators and Editors can create and change assistants. Members can see assistants and ask questions. See [Organisations and roles](/concepts/organizations-and-roles).