Agent Rules - Initial Release 🎉

A declarative rule engine for conversational agents and AI assistants

We're excited to announce the first release of Agent Rules - a powerful PHP library that brings structure and intelligence to conversational interfaces and AI-powered workflows.

What is Agent Rules?

Agent Rules solves a common challenge in building conversational AI: how do you validate unstructured user input in a structured, maintainable way while providing intelligent, interactive feedback?

Think of it as a smart validator that doesn't just say "no" - it guides users through complex processes by asking the right questions at the right time.

The Problem It Solves

Traditional validators are designed for complete data - they check everything at once and return all errors. But conversational interfaces work differently:

❌ Traditional Approach:

"Error: Missing email, password is too short, name is required, terms must be accepted"

✅ Agent Rules Approach:

"What's your email address?"
→ User provides email
"Please create a password (minimum 8 characters)"
→ User provides password
"What's your full name?"
→ User provides name
"Account created! 🎉"

Why We Built This

Modern AI agents and chatbots need to:

✅ Collect information from users step-by-step
✅ Validate data as it arrives (not all at once)
✅ Give helpful feedback when something's wrong
✅ Know when they have everything they need
✅ Handle complex business logic and dependencies

Traditional validators fall short because they're designed for complete data, not conversational flows. Agent Rules bridges this gap.

What Can You Build?

🤖 Conversational AI Assistants

Build chatbots that naturally guide users through multi-step processes like registration, checkout, or support tickets. Works with any AI framework, LLM, or chat interface.

Example conversation:

User: I want to create an account
AI: What's your email address?

User: john@example.com
AI: Great! Now create a password (minimum 8 characters)

User: MyPass
AI: That password is too short. Please use at least 8 characters.

User: MySecurePassword123
AI: Perfect! What's your full name?

User: John Doe
AI: Account created successfully! ✨

🛒 Smart Order Processing

Validate orders interactively, asking for missing details only when needed and providing helpful context.

📋 Interactive Forms & Wizards

Transform complex multi-step forms into conversational experiences that feel natural and forgiving. Perfect for web forms, CLI tools, or terminal interfaces.

🎫 Support & Ticket Systems

Create intelligent agents that validate requests, asking clarifying questions when information is incomplete.

Core Concepts

Four Result Types

Every validation returns one of four structured results that tell your AI or interface exactly what to do next:

Result Type	When to Use	What It Contains
✅ CompleteResult	Everything validated	Success message
🔄 IncompleteResult	Missing or invalid data	What's missing, why it's invalid
🚫 BlockedResult	Action not allowed	Reason for blocking, explanation
⚠️ ErrorResult	System problem	Error details, recovery steps

Each result includes:

Status - What happened (complete, incomplete, blocked, error)
Message - What to tell the user
Context - Specific fields or reasons (missing field, error code, etc.)
Sources - Links to docs, examples, or help resources

How It Works

1. You write simple rules - Each rule checks one thing:

Is the email valid?
Is the password strong enough?
Is the product in stock?

2. The engine orchestrates - It runs rules in the right order and stops at the first problem:

Email rule → ✅ Pass → Password rule → ❌ Fail (too short)
Returns: "Password must be at least 8 characters"

3. Your AI responds - The structured result tells your AI exactly what to ask:

Missing field? Ask for it
Invalid format? Explain why
All good? Proceed to next step

Key Features

🎯 Smart Dependency Resolution

Rules can depend on each other. The engine automatically:

Figures out the correct execution order
Only runs dependent rules after their dependencies pass
Detects circular dependencies

Example: A discount rule depends on product validation and user authentication. It only runs after both pass.

🧩 Composable Logic

Build complex validation from simple building blocks:

Sequence (AND) - All rules must pass
- Email + Password + Name → All required for registration
Any (OR) - At least one must pass
- Credit Card OR PayPal OR Bank Transfer → Any payment method works
Either - Try first, fall back to second
- Try OAuth first, fall back to password → Prefer OAuth but allow passwords

📚 Rich Context with Sources

Results can include helpful references that guide users or AI agents to more information:

{
  "status": "incomplete",
  "missing": "productId",
  "message": "Please provide the product ID",
  "sources": [
    {
      "name": "Product Catalog",
      "reference": "https://shop.example.com/products",
      "content": "Browse our catalog to find product IDs"
    },
    {
      "name": "API Reference",
      "reference": "https://docs.example.com/api",
      "content": "Product IDs are in the 'id' field"
    }
  ]
}

This helps:

Users find what they need
AI agents provide better, contextual responses
Developers debug validation issues

Real-World Example: User Registration

Here's a simplified view of how a registration flow works:

What the user experiences:

User: I want to create an account

AI: What's your email address?
User: john@example.com

AI: Create a password (8+ characters)
User: MyPass

AI: Password must be at least 8 characters
User: MySecurePassword123

AI: What's your full name?
User: John Doe

AI: Account created! 🎉

What's happening behind the scenes:

Each time the AI gets new information, it validates using Agent Rules:

Attempt	Data Provided	Validation Result	AI Response
1	(none)	❌ Email missing	"What's your email?"
2	Email only	❌ Password missing	"Create a password (8+ chars)"
3	Email + weak password	❌ Password too short	"Must be 8+ characters"
4	Email + strong password	❌ Name missing	"What's your full name?"
5	All fields valid	✅ Complete	"Account created!"

The beauty? You only write the validation rules. The engine handles:

✅ Checking in the right order
✅ Stopping at the first problem
✅ Telling your app what's missing
✅ Knowing when everything is complete

Why Agent Rules?

🚀 Developer Experience

Modern PHP - Built for PHP 8.3+ with full type safety
Zero Configuration - Start using it immediately
Framework Agnostic - Works standalone with any framework
Comprehensive Docs - Real examples, not just API references

⚡ Performance & Quality

Short-Circuit Evaluation - Stops at first failure, no wasted work
Fail-Fast Design - Returns feedback immediately
100% Test Coverage - 64 tests, 172 assertions
Production Ready - Used in real projects

🤖 AI-First Design

JSON Serializable - Perfect for AI tool responses
Structured Feedback - AI agents understand the results
Rich Context - Sources help AI provide better answers
Flexible Integration - Use with any AI framework or chat interface

🏗️ Architecture

Immutable - All classes are readonly and final
Type Safe - Full PHP 8.4 generics support
Composable - Rules are building blocks
Testable - Easy to unit test individual rules

Installation

composer require phpro/agent-rules

No configuration required - start using it immediately!

Quick Start

1. Define your data:

class RegistrationRequest {
    public function __construct(
        public readonly ?string $email = null,
        public readonly ?string $password = null,
    ) {}
}

2. Write rules:

class EmailRule implements RuleInterface {
    public function check(mixed $subject): RuleEvaluation {
        if (!$subject->email) {
            return RuleEvaluation::respond(
                new IncompleteResult('email', 'What\'s your email?')
            );
        }
        return RuleEvaluation::pass();
    }
}

3. Run the engine:

$engine = new RuleEngine(new EmailRule(), new PasswordRule());
$result = $engine->evaluate(new RegistrationRequest());

if (!$result->isPass()) {
    echo $result->result->message; // "What's your email?"
}

That's it! See the full documentation for complete examples.

Get Started

📖 Read the documentation - Complete guide with examples

Key sections:

Quick Start - Get up and running in minutes
Result Types - Understanding validation outcomes
Composable Rules - Building complex logic
Dependency Resolution - Automatic rule ordering
Adding Context - Help users with sources
Real-World Examples - Complete implementations

Contributing

We welcome contributions! Whether it's:

🐛 Bug reports and fixes
📚 Documentation improvements
✨ New features and ideas
💡 Use case examples

Questions?

📖 Documentation: See README.md
💬 Discussions: Open a GitHub discussion
🐛 Issues: Report bugs on GitHub
🤝 Contributing: Pull requests welcome!

Built with ❤️ by Phpro

*Making conversational AI smarter, o...

Releases: phpro/agent-rules

Version 0.3.0

What's Changed

New Contributors

Contributors

Uh oh!

Verison 0.2.0

What's Changed

New Contributors

Contributors

Uh oh!

Version 0.1.0

Agent Rules - Initial Release 🎉

What is Agent Rules?

The Problem It Solves

Why We Built This

What Can You Build?

🤖 Conversational AI Assistants

🛒 Smart Order Processing

📋 Interactive Forms & Wizards

🎫 Support & Ticket Systems

Core Concepts

Four Result Types

How It Works

Key Features

🎯 Smart Dependency Resolution

🧩 Composable Logic

📚 Rich Context with Sources

Real-World Example: User Registration

Why Agent Rules?

🚀 Developer Experience

⚡ Performance & Quality

🤖 AI-First Design

🏗️ Architecture

Installation

Quick Start

Get Started

Contributing

Questions?

Uh oh!