Skip to main content

Guides

Provide unstructured context that helps agents interpret questions and respond appropriately.

info
  • Available on the Team and Enterprise plans.
  • Admins, Managers, Editors, and Explorers can view the guides tab.
  • Only Admins and Managers can create, edit, and publish guides.

The guides tab is where workspace context can be defined to help agents interpret questions and respond appropriately across your workspace.

Workspace context​

Workspace context is a single, small text file that the Hex Agent reads in every conversation. Use it to define high-level business context, interaction style, and response expectations that should apply broadly. Keep workspace context concise and focused on information that is relevant to most questions. See Best practices for workspace context.

How to configure workspace context​

Only Admins and Managers can configure workspace context.

To configure workspace context:

  1. Navigate to Context Studio
  2. Find the Guides tab
  3. Click Edit to open the markdown editor
  4. Add your business context, guidelines, and preferences
  5. Click Save to apply the changes

You can also upload a markdown file directly.

Workspace guide library​

The workspace guide library is a collection of text files that the Hex Agent dynamically retrieves when they are relevant to the conversation or task. These files can expose detailed business context that the agent can use to perform specific analyses.

When to use the guide library​

Use the workspace guide library for:

  • Detailed documentation about specific business processes
  • Domain-specific terminology and definitions
  • Step-by-step procedures for common analyses
  • Context that's only relevant to certain types of questions

Unlike workspace context (which is always included), guide library files are selectively retrieved based on relevance, allowing you to provide more detailed context without overwhelming every conversation.

Writing guides​

To make the most of guides, we recommend adding frontmatter to your guide files, which is used by the Hex Agent to determine when a guide is relevant to the conversation or task. Frontmatter is defined at the start of a guide file by --- delimiters, and can include a name and description.

---
name: Customers
description: Understanding Hex's types of customers
---

...

Context Workbench​

The Context Workbench provides tools to manage your library of workspace guides. Admins and Managers can edit existing files and add new ones. The workbench supports multi-player workflows, allowing multiple team members to collaborate on context improvements at the same time.

Once you've made your edits, click Test and Publish. In the Changes view, you can double-check a diff of every edit that has been made. Use the Threads tab to test specific questions and validate how your changes will affect agent responses before publishing them live. This allows you to iterate and immediately verify that agent behavior improves with each edit. Once you're satisfied with the preview, you can publish your changes to your workspace.

Test a thread in the workbench

Programmatically upload guides in CI​

Alternatively, if you manage your guides in GitHub, you can use our GitHub Action to automatically sync your guides from GitHub to Hex. Guides that are synced from GitHub will be read-only in Hex.

info

You can also use our API directly to upload guides and publish guides if you use Gitlab or Bitbucket.

Create a workspace token​

From Settings > API keys, a Workspace Admin will need to create a new workspace token with your desired expiration (“No Expiry” is recommended) and the "Guides" read and write API scope.

In the GitHub UI for your repository, go to Settings > Secrets and Variables > Actions. Create a new repository secret named HEX_API_TOKEN, and set the secret value to the workspace token you just created.

Create a hex_context.config.json file​

In your GitHub repo where your guides live, create a hex_context.config.json at the root of your repository that points to where your guides are. There are 2 different ways to point to guides, paths (i.e. guides/arr.md) or patterns (i.e. guides/*.md - this will match all .md files in the guides folder). Below is a couple of examples of how you can specify which guides you want to upload.

{
  "guides": [
    {
      "path": "path/to/my/guide.md"
    },
    {
      "path": "path_i_want_to_change.md",
      "hexFilePath": "path/that/will/show/up/in/hex.md"
    },
    {
      "pattern": "guides/*.md",
      "transform": {
        "stripFolders": true
      }
    },
    {
      "pattern": "guides/**/*.md"
    }
  ]
}

Add GitHub action​

Next, add a GitHub action by creating a file named hex_context_toolkit.yml inside of a directory of .github/workflows.

# .github/workflows/hex_context_toolkit.yml
name: Publish Hex context

on:
  push:
    branches: [ 'main', 'master' ]
  pull_request:

jobs:
  publish_hex_context:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v6
    - name: Upload guide files
      uses: hex-inc/action-context-toolkit@v1
      with:
        config_file: hex_context.config.json
        token: ${{ secrets.HEX_API_TOKEN }} # Create a workspace token with the Guides write scope and set this in your repository settings
        # optional configuration
        publish_guides: true # publish guides automatically (default true)
        delete_untracked_guides: true # removes guides from hex that were also deleted in your repository (default true)
        hex_url: https://app.hex.tech # For most Hex users, this will be https://app.hex.tech. For single tenant, EU multi tenant, and HIPAA multi tenant customers, replace app.hex.tech with your custom URL (e.g. atreides.hex.tech, eu.hex.tech).

After this, changes to guide files detected by your hex_context.config.json will automatically be kept in sync. You can review and debug actions by looking at the actions tab in the GitHub repository UI and clicking on the hex_context_toolkit workflow.

On this page