Add custom instructions

You can customize how Databricks Assistant responds by adding custom instructions. The assistant considers these instructions when it generates new responses.

For example, instructions can include:

• Information about your preferences, such as which libraries you prefer to use when writing code.
• Context about who you are, such as your name and role.
• Coding conventions to follow.
• Guidelines to follow.
• Directions on how the Assistant should respond, such as using a casual tone.

With the exception of Quick Fix and Autocomplete, Databricks Assistant applies instructions to every response it generates, including Inline Assistant, General Chat, Suggest Fix, Edit mode, and Agent mode.

Databricks Assistant supports two types of instructions: user instructions and workspace instructions. Unless otherwise instructed, the assistant generally prioritizes workspace instructions over user instructions.

Add user instructions

User instructions let you provide system-level instructions to the Assistant. They're a persistent way to share context, preferences, or preferred authoring methods. These instructions are specific to you and are only applied to your interactions with the Assistant.

To add user instructions:

1. Open the Assistant pane by clicking in the upper-right corner of your workspace.

2. In the Assistant pane, click to open the Assistant settings.

   

3. Under User instructions, click Add instructions file. This creates a .assistant_instructions.md file in your default user workspace directory (/Users/<your-username-or-email>) and opens it in a new file tab.

   If you’ve already created an instructions file, click Open instructions file to open the file.

4. Edit the .assistant_instructions.md file to add your custom instructions. Databricks recommends adding your instructions in plain English text, separating each instruction as a new bullet point or paragraph. See Best practices for Assistant instructions.

The Assistant automatically picks up the instructions the next time you interact with it.

You can also use the Assistant to add instructions for you. From the Assistant panel, ask the Assistant to remember something.

Add and view workspace instructions

note

Only Workspace admins can add or edit workspace instructions.

Workspace instructions are configured by your workspace admin and provide more context to the Assistant to help it follow guidelines and operate more efficiently in your workspace.

If your workspace does not have workspace instructions yet, a workspace adminstrator can create the instructions file by following these steps:

1. In the Workspace/ directory of the workspace, create a file named .assistant_workspace_instructions.md.
2. Edit the file to add instructions for the Assistant that should apply workspace-wide. Databricks recommends adding your instructions in plain English text, separating each instruction as its own bullet point or paragraph. See Best practices for Assistant instructions.

The Assistant automatically picks up the new workspace instructions the next time a user interacts with it.

To view or edit workspace instructions:

1. Open the Assistant pane by clicking in the upper-right corner of your workspace.

2. In the Assistant pane, click to open the Assistant settings.

3. Under Workspace instructions, click View file. This opens the .assistant_workspace_instructions.md file in a new tab.

4. If you’re a workspace administrator, you can edit the file and add instructions that apply to the Assistant’s behavior throughout the workspace. See Best practices for Assistant instructions for more information on adding instructions.

   If you’re not an admin, you can still view the file to understand what instructions the Assistant is following in addition to any user instructions you may have provided.

   

Best practices for Assistant instructions

It’s important to consider the potential limitations of the Assistant when providing instructions. Here are some general guidelines and tips for writing instructions to optimize your experience and get the most out of this feature.

• Write clear, specific instructions: Be explicit and unambiguous when writing your instructions.
• Keep instructions under 20,000 characters: Instruction files are limited to 20,000 characters. Any instructions past this limit will not be used by the Assistant. Be concise and prioritize important instructions.
• Use headings and delimiters for structure: Instructions are in Markdown files. Use Markdown formatting in your instructions to provide structure. Use bullet points as delimiters to separate out distinct instructions. Use headings to group together a set of instructions. For example, you might have a heading for "Python code conventions" that includes a bulleted list of Python-specific guidelines that the Assistant should follow when working with Python code.
• Scope: The Assistant applies instructions to every response it generates when you interact with it using Inline Assistant, General Chat, Suggest Fix, Edit mode, etc. However, the Assistant does not consider instructions for Quick Fix and Autocomplete. Keep instructions broadly relevant to different Assistant functions to avoid unintended behavior.
• Provide context and references: While the Assistant uses surrounding context like notebook code and table metadata, it does not yet proactively fetch additional information based on the instructions. To ensure helpful responses, include any key details directly in the instructions, such as when to use a particular table or function.