Guidelines give AI Agents project-specific context that generic AI models don't have. Without them, agents produce output for general use. With them, agents apply your brand vocabulary, audience expectations, and compliance constraints on every run.

You can create guidelines once and reuse them across agents. A single Brand Voice guideline, for example, can be assigned to both your Translator agent and your Content summarizer, so both produce output that sounds like your brand.

#Guideline categories

Hygraph provides four categories. Each maps to a distinct type of context that agents use differently.

#Audience & Context

Audience & Context guidelines define target personas, reading level, and cultural considerations. This shapes how agents frame and pitch generated output.

A technical audience guideline and a general consumer guideline produce measurably different summaries from identical source content. The difference shows up in assumed knowledge and word choice rather than structure.

Best practices

• Describe the audience's existing knowledge level, not just their role. "Enterprise IT administrators" tells an agent less than "Enterprise IT administrators who are familiar with SSO and directory services but may not have prior experience with headless CMS architecture." The second version reduces the chance of the agent over-explaining basics or under-explaining concepts that matter.
• Include the content's destination alongside the audience. The same reader behaves differently when scanning a product listing versus reading onboarding documentation. Specifying both narrows the agent's output range in a way that audience description alone does not.

#Brand Voice & Tone

Brand Voice & Tone guidelines define your brand's personality, writing style, and editorial rules. Agents apply this when generating or transforming text, such as summarizing, rewriting, or producing localized copy.

Write this as a concise description of how your brand communicates. "Conversational but authoritative. Short sentences. No jargon." gives an agent more to work with than a list of banned words.

Best practices

• Include a positive and a negative example for your most important style rules. Telling an agent "write conversationally" is less effective than showing it one sentence that is on-brand and one that is not. The contrast gives the model a calibration point rather than an abstract instruction.
• Separate voice from tone if they differ by content type. Your brand might use the same voice across all content but use a more formal tone for legal notices than for product descriptions. Capturing that distinction in the guideline prevents agents from applying blog-post tone to compliance copy.

#Legal & Compliance

Legal & Compliance guidelines define required disclaimers, restricted language, and regulatory constraints.

Be specific. "Avoid implying guaranteed returns" is actionable. "Follow legal guidelines" is not.

Best practices

• Write restrictions as observable behaviors, not principles. "Do not use the word 'guarantee' or any synonym implying certainty of outcome" is enforceable by an agent. "Be careful about regulatory language" is not as it shifts interpretation to the model, which will interpret it optimistically.
• Review this guideline whenever your legal or regulatory context changes. Unlike brand voice, compliance requirements change on external schedules you don't control. A guideline that was accurate when written can become incorrect after a product update, a jurisdiction change, or a regulatory revision. Assign ownership of this guideline to someone who owns this area of responsibility.

#Glossary

Glossary guidelines define key terms, definitions, and translation rules for consistent terminology. Use this for product names, legal terminology, or brand vocabulary that must not be paraphrased or mistranslated.

A glossary is organized into term groups. Each term group represents a single concept and holds one term per locale in your project. Locales already added to a term group do not appear in the locale selector when adding further entries, so each locale can only appear once per term group. The Translator agent uses these entries directly when producing localized output.

Best practices

• Cover edge cases, not just obvious terms. Product names are easy. The harder wins come from abbreviations, plural forms, and terms that have acceptable translations in general usage but wrong ones in your domain. For example, "checkout" in an e-commerce context should stay as "checkout" in German, not be translated to "Kasse" (cash register), which carries the wrong meaning for an online store.
• Keep the glossary focused. Prioritize terms, such as brand names, legal designations, and UI labels, where mistranslation might cause real problems.

#Permissions

By default, Guidelines permissions are granted as follows:

Non-admin users can view existing guidelines and see which guidelines are assigned to an agent, but cannot create, edit, or delete them. If your team needs editors or other roles to manage guidelines, an Admin can update these permissions in Project Settings > Roles & Permissions.

#Limits

Plan your guideline budget before creating them. A project running three agents could quickly exhaust the project limit with no overlap. Alternatively, you can share guidelines strategically to cover more ground.

Free or self-service plan users can use guidelines for AI Assist tasks only.

#Create a guideline

#Markdown guideline

Markdown guidelines cover Audience & Context, Brand Voice & Tone, and Legal & Compliance.

1. Go to AI Hub > Configurations > Guidelines.
2. Click Add Guideline and select a category: Audience & Context, Brand Voice & Tone, or Legal & Compliance.
3. Enter a Name, and click Add.
4. Write your guideline content in Markdown in the Document tab. You can use headings, lists, tables, and images to structure the guideline.
5. Click Save.

The guideline is immediately available to assign to any agent or use in any AI Assist task in the project.

#Glossary

1. Go to AI Hub > Configurations > Guidelines.
2. Click Add Guideline and select Glossary.
3. Enter a Name, and click Add Glossary.
4. Add your terms. See Add terms to a glossary or import a glossary from a template.
5. Click Save.

The glossary is immediately available to assign to any agent or use in any AI Assist task in the project.

#Add terms to a glossary

Terms are organized into term groups. Each term group represents one concept and holds one term per locale.

To add a term group:

1. Click Add term group.
2. Enter the term and choose the locale.
3. Enter an optional Definition.
4. Click Add.

To add terms for additional locales to the same term group:

1. Click + next to the term group.
2. Enter the term and choose the locale. Locales already added to this term group do not appear in the selector.
3. Enter an optional Definition.
4. Click Add.

Repeat until all required locales are covered for that term group. To add another concept, click Add term group again.

You can also edit or delete term groups and terms using the following actions:

• Edit a term group name: Click the (pencil icon) next to the term group name.
• Edit an individual term: Click the (pencil icon) next to that term entry.
• Delete a term group or individual term: Click the (delete icon) next to the item you want to remove.

#Import a glossary from a template

1. On the Glossary creation screen, click Download CSV template.
2. Fill in your term entries in the spreadsheet. Each row requires a Term Group, Locale, and Term. Definition is optional.
3. If the Import button is not visible, click Add term group to make it appear.
4. Click Import to upload the completed file.

Importing overwrites any terms already entered manually in the same glossary. Review existing terms before importing.

#Assign a guideline

Guidelines can be assigned to agents and AI Assist tasks.

#To an agent

Guidelines are assigned inside the agent configuration. To assign a guideline to an existing agent:

1. Go to AI Hub > Agents.
2. Click the pencil icon on the agent card.
3. Under Guidelines, select guidelines from the list.
4. Click Save.

To assign during initial setup, select guidelines under the Guidelines field in the agent configuration flow. See Set up AI Agents for the full configuration steps.

#To an AI Assist task

Guidelines can also be assigned when running an AI Assist task. To assign a guideline to an AI Assist task:

1. Open an entry in the content editor.
2. Click AI Assist in the top bar.
3. Under Guidelines, select guidelines from the list.
4. Configure and run your task as normal.

The selected guidelines apply to that task run only. They are not saved as a default for future AI Assist sessions.

#Manage a guideline

To edit a guideline, click Edit on the guideline in AI Hub > Configurations > Guidelines. Each guideline category has its own card.

#Markdown-based guideline

Open a Markdown-based guideline (Brand Voice & Tone, Audience & Context, and Legal & Compliance) to edit its name and content, and view its version history:

• Document: Edit the guideline name and content.
• Versions: View the version history and compare changes between versions. Compare the current version with any previous version. The diff is available in two views:
  • Split view: Displays the two versions side by side.
  • Line by line: Displays changes inline.

#Glossary

Open a glossary to manage its terms, name, and version history:

• Terms: Add, edit, and delete term groups and individual term entries.
• Settings: Edit the glossary name.
• Versions: View the version history of the glossary. Compare the current version with any previous version. Version restore is not currently available.

#Delete a guideline

You can delete a guideline from the guideline card in AI Hub > Configurations > Guidelines. Click the context menu and select (delete icon) next to the guideline you want to remove.

Deleting a guideline removes it from any agents or AI Assist tasks it is assigned to. This action is irreversible.

#Guidelines vs. custom instructions

Agents support two ways to shape output. They serve different purposes and can be used together.

Use guidelines for anything that should apply consistently across multiple agents or over time. Use custom instructions for output-specific guidance that applies only to a single agent's task.

#What's next

• AI Agents: Understand how agents use guidelines at runtime alongside custom instructions.
• Set up AI Agents: Configure an agent and assign guidelines during setup.
• Use AI Assist: Use guidelines when running AI Assist tasks in the content editor.
• Billing: Monitor AI token consumption for your project.