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

# Custom agents

> Build AI agents with custom instructions, knowledge sources, and actions tailored to your team's use cases.

Agents are customized AI assistants you configure for specific roles or workflows — a support agent that knows your help docs, an onboarding agent with access to your internal wiki, or a sales agent with CRM context. Each agent has its own instructions, knowledge, tools, and sharing settings.

## What you can configure on an agent

<CardGroup cols={2}>
  <Card title="Custom instructions" icon="pencil">
    Write a system prompt that defines how the agent behaves, what tone it uses, and what tasks it focuses on.
  </Card>

  <Card title="Knowledge sources" icon="database">
    Attach document sets, specific folders, channels, or individual files from your connected sources.
  </Card>

  <Card title="Tools and actions" icon="bolt">
    Enable tools like web search, code interpreter, or external actions via MCP so the agent can interact with your systems.
  </Card>

  <Card title="LLM override" icon="cpu">
    Pin the agent to a specific model and provider, overriding the default LLM for all conversations with that agent.
  </Card>

  <Card title="Starter messages" icon="message-circle">
    Add suggested prompts that appear when a user opens the agent, guiding them toward its intended use cases.
  </Card>

  <Card title="Sharing controls" icon="users">
    Share the agent with specific users, groups, or your entire organization. Featured agents appear at the top of the agent list.
  </Card>
</CardGroup>

## Create an agent

<Steps>
  <Step title="Open the agent builder">
    Go to **Admin → Agents** and click **New Agent**.
  </Step>

  <Step title="Name and describe your agent">
    Give the agent a name and a short description. The description appears in the agent picker and helps teammates understand what the agent is for.
  </Step>

  <Step title="Write the system prompt">
    In the **Instructions** field, write the system prompt for the agent. Be specific about its role, tone, and any constraints. For example:

    ```text theme={null}
    You are a support agent for Acme's internal IT helpdesk. Answer questions
    using the IT knowledge base. If you cannot find an answer, tell the user
    to submit a ticket at help.acme.internal. Keep responses concise.
    ```

    To give the agent full control over its behavior (replacing the default Onyx system prompt entirely), enable **Replace base system prompt**.
  </Step>

  <Step title="Select knowledge sources">
    Under **Knowledge**, attach the document sets, connector folders, or individual files the agent should use to answer questions. You can also set a search start date to limit how far back the agent looks.
  </Step>

  <Step title="Enable tools">
    Under **Tools**, toggle on any capabilities you want the agent to have:

    * **Search** — search across its attached knowledge sources
    * **Web Search** — search the live web
    * **Code Interpreter** — execute code in a sandbox
    * **Image Generation** — generate images from prompts
    * **Custom actions** — interact with external systems via configured MCP or action tools
  </Step>

  <Step title="Set the LLM (optional)">
    If you want the agent to use a specific model, select a provider and model under **LLM Override**. Leave this blank to use your organization's default model.
  </Step>

  <Step title="Configure sharing">
    Choose who can see and use the agent:

    * **Public** — visible to all users in your organization
    * **Specific users or groups** — visible only to the people you select

    Toggle **Featured** to pin the agent to the top of the agent list for all users.
  </Step>

  <Step title="Save and test">
    Click **Save**. Open a new chat, select your agent from the agent picker, and send a test message to verify it behaves as expected.
  </Step>
</Steps>

## Add actions

Actions let an agent do more than answer questions — they let it interact with external tools. Onyx supports actions via MCP (Model Context Protocol), with flexible auth options.

<AccordionGroup>
  <Accordion title="What are actions?">
    Actions are tools an agent can call during a conversation to retrieve live data or trigger operations in external systems — for example, looking up a ticket in Jira, checking inventory in an ERP, or sending a Slack message.
  </Accordion>

  <Accordion title="How do I set up actions?">
    Go to **Admin → Actions** to configure MCP server connections. Once an action is configured, you can enable it on any agent under the **Tools** section of the agent builder.
  </Accordion>

  <Accordion title="Can I restrict which users can use actions?">
    Yes. Role-based access control (RBAC) applies to actions. Admins can restrict access to sensitive actions to specific roles or groups.
  </Accordion>
</AccordionGroup>

## Manage agents

From **Admin → Agents**, you can:

* Edit an existing agent's configuration
* Toggle visibility (listed or unlisted)
* Mark an agent as featured
* Delete agents you no longer need

Usage analytics for each agent are available in **Admin → Analytics**, broken down by team, LLM, and agent.