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

Custom instructions

Write a system prompt that defines how the agent behaves, what tone it uses, and what tasks it focuses on.

Knowledge sources

Attach document sets, specific folders, channels, or individual files from your connected sources.

Tools and actions

Enable tools like web search, code interpreter, or external actions via MCP so the agent can interact with your systems.

LLM override

Pin the agent to a specific model and provider, overriding the default LLM for all conversations with that agent.

Starter messages

Add suggested prompts that appear when a user opens the agent, guiding them toward its intended use cases.

Sharing controls

Share the agent with specific users, groups, or your entire organization. Featured agents appear at the top of the agent list.

Create an agent

1. Open the agent builder

   Go to Admin → Agents and click New Agent.

2. 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.

3. 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:

   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.

4. 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.

5. 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
6. 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.

7. 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.

8. 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.

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.

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.

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.

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.

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.