Download the PHP package phpro/agent-rules without Composer

Agent Rules

A declarative rule engine designed for conversational agents, AI assistants, and interactive workflows.

Perfect for building chatbots, AI agents, CLI wizards, or any system that guides users through multi-step processes by asking questions and validating responses.

Overview

Agent Rules provides a logical processing unit for handling unstructured input in a structured and interactive way. It enables you to define validation rules that can request missing information, enforce business logic, and provide intelligent feedback to users or AI agents.

Built to be compatible with Symfony AI Agent, this library integrates seamlessly with AI-powered tools and conversational interfaces.

Key Features

• Declarative Rule Definition: Define validation logic as composable rule objects
• Automatic Dependency Resolution: Rules declare dependencies, engine handles execution order
• Interactive Feedback: Rules can request missing data with structured result types
• Composable Logic: Combine rules with Sequence (AND), Any (OR), and Either patterns
• Type-Safe: Full PHP 8.4+ type safety with readonly classes and generic support
• Framework Agnostic: Works independently with optional Symfony AI integration

Installation

Quick Start

1. Define Your Subject

The subject is the data being validated:

2. Create Validation Rules

Each rule checks one aspect and can request missing information:

3. Run the Engine

Result Types

The engine provides four result types to communicate different states:

Complete Result

Incomplete Result

Blocked Result

Error Result

Composable Rules

Sequence (AND Logic)

All rules must pass. First failure stops execution:

Any (OR Logic)

At least one rule must pass:

Either (Binary Choice)

Try left, fall back to right:

Dependency Resolution

Rules can declare dependencies to ensure proper execution order:

The engine automatically:

• Resolves dependency order using topological sort
• Detects cyclic dependencies
• Validates that all dependencies exist

Adding Context with Sources

You can attach contextual information to results that helps users or AI agents understand where to find more information:

Sources are particularly useful for:

• Documentation links
• Example values
• Help text
• Related resources
• API references

Symfony Configuration

Configure the rule engine as a service:

Tag your rules:

Real-World Example: Form Validation Assistant

Imagine building a conversational AI that helps users complete a multi-step registration form. The AI needs to:

• Ask for information in the right order
• Validate data as it's provided
• Give helpful feedback on errors
• Know when all required data is collected

Implementation

1. Define the Request Context

2. Create Validation Rules

3. Create the AI tool

This is an example of linking the rule engine to a Symfony AI agent tool:

With following agent configuration:

Conversation Flow

Use Cases

Chatbot Form Wizards

Guide users through complex forms by requesting one piece of information at a time based on validation rules.

AI-Powered Customer Support

Validate customer requests interactively, asking clarifying questions when information is missing or invalid.

CLI Configuration Tools

Build interactive command-line tools that guide users through setup by validating configuration step-by-step.

API Request Validation

Validate API requests from AI agents, providing structured feedback on missing or invalid parameters.

Document Processing Workflows

Check documents for completeness, requesting missing sections or data from users or automated systems.

Advanced Patterns

Conditional Rules

Nested Composites

Stateful Rules

Testing

Architecture

Design Principles

• Immutability: All classes are readonly and final for predictable behavior
• Type Safety: Full generic support with @template annotations
• Composition: Rules are composable building blocks
• Separation of Concerns: Each rule validates one aspect
• Fail-Fast: Short-circuit evaluation stops on first failure

Core Components

Performance Considerations

• Short-Circuit Evaluation: Execution stops at first failure
• Lazy Evaluation: Only evaluates rules in dependency order
• Topological Sort: O(V + E) dependency resolution using PSL Graph
• No Reflection: Pure constructor injection, no runtime reflection overhead

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License. See LICENSE file for details.