# Agents (/docs/ai/agents)



An Agent is a saved assistant configuration: a model, a system prompt, and optional knowledge sources and MCP Servers. It lets you reuse a task-specific assistant without configuring each conversation again. Creating an Agent does not deploy or train a model.

## Before you begin [#before-you-begin]

Open **Chat & Work → Agents** in the intended tenant. You need Agent create permission and access to the model and sources you select. Using, updating, sharing, and deleting Agents have separate operation permissions and resource-access checks.

For knowledge-grounded answers, prepare an indexed file or folder in [Files](/docs/use/portal/chat-and-work#files). For tools, first [link your own MCP credential](/docs/ai/mcp/link-your-credential) where required. A tenant administrator configures available [web-search providers](/docs/administration/tenant-settings).

## Create an Agent [#create-an-agent]

1. Select **New Agent**.
2. Enter **Agent name** and **Description** so others can identify its purpose.
3. Choose **AI Model** from the available models.
4. Write **System Prompt** with the task, expected answer format, and how to handle missing information.
5. Optionally choose a web-search provider, a file or folder, and MCP Servers as described below.
6. Select **Create Agent**.
7. Open a new chat, select the Agent from the model selector, and send a representative question.
8. Inspect the answer and any retrieval or tool activity. Verify the intended sources, not just that a response appeared.

For example, a support Agent can use a product-manual folder and a prompt asking it to cite retrieved material and state when the manuals do not answer the question.

### Choose a web-search provider [#choose-a-web-search-provider]

In the Agent configuration, select one configured provider or **No search provider**. Disabled or incompletely configured providers are not selectable.

The saved provider makes web search available to the Agent without requiring the ordinary chat Search toggle. It constrains search to that provider; a failing configured provider does not silently switch to an unrelated default provider. The model still decides when to call the search tool.

### Choose a file or folder [#choose-a-file-or-folder]

1. In **Files**, select **Browse**.
2. Browse your files or switch to shared files. Open folders to inspect their contents.
3. Select one file or one folder, then confirm with **Select**.
4. Use **Change** to replace it or **Remove** to clear it before saving the Agent.

The Portal selects at most one file or folder for an Agent. A file must be **RAG Available**. A folder can be selected before all its files are ready; usable contents are resolved at request time, subject to indexing and the caller's access.

A saved source makes file retrieval available without manually enabling it for each prompt. When the Agent has a configured file or folder, it supplies the retrieval scope instead of the ad hoc files or folders chosen in the chat RAG picker. It does not combine the two scopes. To ask about different material, change the Agent's source, use another Agent, or select a raw model and choose the desired RAG scope.

### Choose MCP Servers [#choose-mcp-servers]

Select the MCP Servers the Agent should be able to use. Each person using the Agent must link their own credential unless the server is configured as unauthenticated. Sharing an Agent does not lend the creator's credentials or grant access to the upstream system.

See [Use an MCP Server in chat](/docs/ai/mcp/use-in-chat) for connection and tool checks.

## Use and verify an Agent [#use-and-verify-an-agent]

Select the Agent from the chat model selector. For the first test, ask something whose answer you can verify against its source, then inspect the retrieved context or tool results.

A configured source or tool is available to the assistant; it does not guarantee that every answer will call it or cite it. If a grounded answer is required, state that in the prompt and inspect the result.

[Skills](/docs/ai/skills) can add reusable task instructions to an Agent's text conversation. In [Voicebot](/docs/ai/voicebot), only the Agent's model and system prompt apply: its knowledge sources and MCP tools do not.

## Update an Agent [#update-an-agent]

1. Find the Agent by name or model, using the **All Agents**, **My Agents**, or **Shared Agents** filter as needed.
2. Open its action menu and select **Edit**.
3. Change its model, prompt, description, sources, or MCP Servers.
4. Select **Update Agent** and wait for the saved result.
5. Test the updated configuration in a new chat.

The edit action can be offered to a reader with update-operation permission. Saving still requires owner or editor access to that Agent. Administrator status alone does not confer access to another person's private Agent.

## Share an Agent [#share-an-agent]

The creator can open **Share** when they have permission to manage resource grants. Add tenant users or groups, choose **Viewer** or **Editor**, and select **Save**. Group assignments apply to the group's members.

| Role   | What it allows, with the corresponding operation permissions |
| ------ | ------------------------------------------------------------ |
| Viewer | Read and use the Agent.                                      |
| Editor | Read, use, and update its configuration.                     |
| Owner  | Also manage sharing and delete the Agent.                    |

Share the required files or folders separately. Retrieval is checked against the person asking the question, not the creator's access. Also have each recipient link any required MCP credentials. Verify the shared Agent using a recipient's own account before relying on it for a team workflow.

## Delete an Agent [#delete-an-agent]

Open the Agent's action menu, select **Delete**, and confirm **Delete Agent**. This requires ownership and delete permission. Everyone it is shared with loses access to the configuration. Deletion cannot be undone; it is not a way to erase already delivered conversation content.

## Resolve common problems [#resolve-common-problems]

* **Model unavailable:** choose an accessible model and verify it in [AI Hub](/docs/use/portal/ai-hub#available-models).
* **File cannot be selected:** wait for **RAG Available** or correct failed indexing in Files.
* **Source missing for a recipient:** check the recipient's tenant, source sharing, and indexing status separately from Agent sharing.
* **No web results:** check the selected provider's configuration and availability. Removing it returns the Agent to ordinary chat search behavior.
* **MCP tools missing:** check the user's linked credential and the server's allowed tools.
* **Update refused:** ask the owner for editor access; an available Edit button is not proof of write access.

## Configure through the API [#configure-through-the-api]

Applications can create configurations with `POST /v1/agents` and update them with `PUT /v1/agents/{config_id}`, using the corresponding `agent.configuration.*` permissions and resource access. See the deployment's [live API reference](/docs/reference) for authentication and complete schemas.

The source fields are `web_search_provider_ids` and `file_folder_ids`. They contain tenant resource UUIDs, not search URLs or file paths. The API accepts a list of sources, with at most 50 file/folder IDs; the Portal authoring form selects one provider and one file or folder. Do not assume the Portal can author an arbitrary multi-source API configuration.

On update, an omitted or `null` source list leaves it unchanged; `[]` clears it. For example, this update removes configured knowledge sources without replacing the model or prompt:

```json
{
  "web_search_provider_ids": [],
  "file_folder_ids": []
}
```

Configured knowledge is used by ordinary Portal text chat and the Responses integration when invoking the Agent. File access is resolved again for the caller at request time. Voice conversations use only the model and prompt.

## Related pages [#related-pages]

* [RAG](/docs/ai/rag)
* [Skills](/docs/ai/skills)
* [MCP Servers](/docs/ai/mcp)
* [Voicebot](/docs/ai/voicebot)