Zum Inhalt

Rule

Rule defines behavioral guidelines and constraints for AI agents. Rules are static text strings injected as system context in each request.

Overview

Rules guide agent behavior through:

  • Static Rules: Always-active behavioral guidelines injected into the provider context
  • Simple API: Single constructor, single string argument
  • Context-Aware: Injected by providers as part of the system prompt

Key Features

  • ✅ Simple single-constructor API
  • ✅ Injected into every provider call
  • ✅ Type-safe with full TypeScript support

Constructor

new Rule(description: string)

Creates a rule that is always active.

Parameters: - description: Textual description defining the behavior. Must be a non-empty string.

Example:

import { Rule } from '@arcaelas/agent';

const politeness = new Rule("Maintain a professional and courteous tone");
const privacy = new Rule("Never share user personal information");
const helpfulness = new Rule("Provide comprehensive and useful answers");

Note: The conditional new Rule(description, { when }) overload documented in older versions does not exist in the current codebase. There is only one constructor signature.

Properties

description

readonly description: string

Human-readable description of the behavioral guideline.

Example:

const rule = new Rule("Always validate user input");
console.log(rule.description); // "Always validate user input"

length

get length(): number

Returns the character length of the description.

Example:

const rule = new Rule("Maintain professional tone");
console.log(rule.length); // 26

Methods

toJSON()

toJSON(): { description: string }

Serializes the rule to a plain object.

Example:

const rule = new Rule("Be polite");

console.log(JSON.stringify(rule));
// {"description":"Be polite"}

const data = rule.toJSON();
console.log(data.description); // "Be polite"

toString()

toString(): string

Returns string representation for debugging. Long descriptions are truncated to 50 characters.

Returns: String in format "Rule: description"

Example:

const rule = new Rule("Always provide detailed explanations");
console.log(rule.toString());
// "Rule: Always provide detailed explanations"

const long_rule = new Rule("This is a very long rule description that will be truncated when displayed");
console.log(long_rule.toString());
// "Rule: This is a very long rule description that wi..."

Usage Patterns

Pattern: Static Behavioral Guidelines

const night_mode = new Rule(
  "Use concise responses and suggest using the callback feature when replying outside business hours."
);

const weekend_rule = new Rule(
  "Inform the user that technical support is limited on weekends."
);

Pattern: Tier-Based Rules via Metadata (using metadata at provider level)

Since Rule does not support conditional evaluation, apply tier-specific rules by setting them dynamically before the agent call:

const base_rules = [new Rule("Be helpful and concise")];
const premium_rules = [new Rule("Offer priority support and premium benefits")];

const tier = agent.metadata.get("user_tier", "basic");
agent.rules = tier === "premium"
  ? base_rules.concat(premium_rules)
  : base_rules;

Pattern: Regional Compliance

const gdpr_rule = new Rule(
  "Apply GDPR compliance: inform the user about their data rights and provide data access options."
);

const ccpa_rule = new Rule(
  "Apply CCPA compliance: provide opt-out options for data collection."
);

// Set before call based on user region
const region = agent.metadata.get("user_region", "");
if (region === "EU" || region === "UK") {
  agent.rules = agent.rules.concat(gdpr_rule);
} else if (agent.metadata.get("user_state") === "CA") {
  agent.rules = agent.rules.concat(ccpa_rule);
}

Best Practices

1. Clear Descriptions

Write explicit, actionable rule descriptions:

// ✅ Good: Clear and specific
new Rule("Always ask for order confirmation before processing payment");
new Rule("Verify user identity using two-factor authentication for account changes");

// ❌ Bad: Vague
new Rule("Be careful");
new Rule("Handle properly");

2. Actionable Descriptions

Each rule should be self-contained and actionable by the LLM:

// ✅ Good: Specific, actionable
new Rule("Always ask for order confirmation before processing payment.");
new Rule("When the user seems frustrated, acknowledge their concern and offer to escalate.");

// ❌ Bad: Vague
new Rule("Be careful");
new Rule("Handle properly");

3. One Concern Per Rule

Keep rules focused:

// ✅ Good: One concern per rule
const privacy = new Rule("Never share user personal information with third parties.");
const tone = new Rule("Maintain a professional and friendly tone.");

// ❌ Bad: Multiple concerns
new Rule("Be professional, never share data, and always upsell premium features.");

Type Safety

Rule is fully typed with TypeScript:

import { Rule } from '@arcaelas/agent';

const rule: Rule = new Rule("Always validate user input");

// Properties are correctly typed
const description: string = rule.description;
const length: number = rule.length;

// toJSON returns { description: string }
const json: { description: string } = rule.toJSON();

Next: Learn about Message →