Skip to main content
Rules are instructions that guide the agent’s behavior — encoding business definitions, calculation methods, domain terminology, and analytical approaches the agent should follow when answering questions. Rules are configured as code in your data model repository, alongside your cubes and views. This enables version control, code review, and consistent behavior across environments.

​
Rule types

For agent_requested rules, the description field is what the agent matches against the user’s request to decide whether the rule is relevant — write it as a short summary of when this rule applies. always rules don’t need a description since they’re injected into every interaction regardless.

​
Defining rules

Rules are defined as Markdown files under agents/rules/. Each rule lives in its own file: the YAML frontmatter holds metadata, and the Markdown body is the rule prompt.
For agent_requested rules, add a description so the agent can decide when the rule applies:
Files placed under a rules/ directory are treated as rules automatically — no kind property is required. The name is inferred from the file name (e.g., fiscal-year.md → fiscal-year).

​
Frontmatter properties

​
Inlining rules in YAML

You can also inline rules directly in agents/config.yml under a rules key:
Inline rules accept the same properties as Markdown rules — name, description, prompt (required), type (required), and conditions.
Rules inlined at the root of agents/config.yml are attached to the implicit auto space and applied to the default agent in a single-agent setup. In a multi-agent setup, attach rules to a specific space by inlining them under that space’s rules key (or by placing Markdown files under agents/rules/<space-name>/).

​
Limiting a rule to some users

By default, a rule applies to every user of the agent. Add conditions to apply it only to users who meet all of them — for example, one client’s naming conventions in a deployment that serves several clients through signed embedding.
  • Conditions see the same user attributes and groups as access policies. A user without the attribute or group doesn’t get the rule.
  • values are strings. Quote numbers and booleans ("00123", "true") — YAML would read an unquoted 00123 as 123.
  • Only conditions limits a rule. Any other key on a rule without conditions, such as marketplace_id: acme, is ignored, and the rule applies to everyone.
Conditions decide which instructions the agent receives; they don’t restrict data. Use access policies to control what each user can query.

​
Writing effective rules

Good rules are specific, actionable, and encode context the agent wouldn’t otherwise know about your business. Do:
  • “Customer churn rate is customers lost ÷ total customers at the start of the period.”
  • “When analyzing quarterly performance, always compare against the same quarter of the previous year.”
  • “Our fiscal year starts in October.”
Don’t:
  • “Be helpful.” (too vague)
  • “Always be accurate.” (redundant)
  • “Consider all factors.” (too broad)

​
Domain examples

E-commerce:
SaaS:

​
Resolving conflicts

When multiple rules could apply, follow these guidelines:
  1. Review existing rules before adding new ones to avoid contradictions.
  2. Use specific triggers in agent_requested rules so the agent knows when each rule applies.
  3. Prefer specificity over breadth — narrowly scoped rules override broader defaults more cleanly.
  4. Test rule combinations with sample queries before relying on them.
If two always rules directly contradict each other, the agent will surface the conflict in its response. Resolve such conflicts by editing the rules in your repository and redeploying.