adachsoft/agent-rule-tool

SPI tools for exposing and administrating agent rules in the AdachSoft AI tool call ecosystem.

v0.3.0 2026-03-03 08:19 UTC

Requires

• php: ^8.3
• adachsoft/agent-rule-contract: 0.6.0
• adachsoft/ai-tool-call: ^2.0.1

Requires (Dev)

• adachsoft/agent-rule: 0.4.0
• adachsoft/php-code-style: 0.3.1
• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• rector/rector: ^2.3.3

MIT

• Arkadiusz Adach

• tools
• rules
• Agent
• ai
• adachsoft
• ai-tool-call

README

SPI tool agent_rule for adachsoft/ai-tool-call that exposes effective agent rules from RuleReaderInterface as structured JSON, and SPI tool agent_rule_admin for creating, updating and deleting rules via RuleWriterInterface.

Tool definitions

agent_rule

• Tool name: agent_rule
• Description: Returns effective agent rules resolved by the injected rule reader.
• Tags: ['agent:rules', 'rules', 'agent:general']

agent_rule_admin

• Tool name: agent_rule_admin
• Responsibility: create, update and delete rules using RuleWriterInterface while enforcing the same content-size limits as the agent_rule tool.

Input parameters for agent_rule (JSON, snake_case)

{
  "project_id": 1 // optional, integer or null; when omitted or null -> only global rules; when integer -> global + project rules
}

Rules:

• project_id may be integer, null or absent.
• Any other type for project_id causes InvalidToolCallException.

Mapping to reader:

• missing / null -> getAllByProject(null) (only global rules)
• integer 1 -> getAllByProject(1) (global + project rules for project 1)

Output shape for agent_rule (KeyValueMap → JSON)

The tool result is a KeyValueMap that can be serialized to JSON with the following shape:

{
  "project_id": 1,       // integer or null
  "count": 2,            // number of rules
  "rules": [
    {
      "id": "rule_1",          // RuleId as string
      "type": "REQUIREMENT",   // RuleTypeEnum::name
      "target": "AGENT",       // RuleTargetEnum::name
      "content": "...",        // string
      "priority": 100           // integer
    }
  ]
}

Notes:

• rules[*].type / target are string values from corresponding enums in adachsoft/agent-rule-contract (RuleTypeEnum::name, RuleTargetEnum::name).
• metadata from Rule is intentionally not exposed.
• Sorting is stable by priority descending and preserves original order for ties.

Safety limits (ConfigMap, shared)

Both tools share the same configuration object AgentRuleToolConfig, which is built from a ConfigMap passed to the factories under the tool names agent_rule and agent_rule_admin.

Supported keys (snake_case):

• max_rules (int, default: 100)
• max_rule_content_bytes (int, default: 500)
• max_payload_bytes (int, default: 64000)

Semantics:

• max_rules: maximum number of rules included in the agent_rule response.
• max_rule_content_bytes: maximum strlen(content) per rule; enforced centrally for both read and write paths:
  • agent_rule: refuses to return rules whose content exceeds this limit.
  • agent_rule_admin: refuses to create or update a rule whose content exceeds this limit.
• max_payload_bytes: maximum strlen(json_encode(finalResult)) for the whole agent_rule payload.

Exceptions:

• invalid input types -> InvalidToolCallException
• invalid config (types, <=0) -> ToolConfigurationException
• exceeded limits (max_rules, max_rule_content_bytes, max_payload_bytes) -> ToolExecutionException
• exceptions from RuleReaderInterface / RuleWriterInterface are propagated as-is.

Quick Start (agent_rule)

1. Install dependencies in your project:

composer require adachsoft/ai-tool-call adachsoft/agent-rule-contract adachsoft/agent-rule-tool

1. Implement AdachSoft\\AgentRuleContract\\Contract\\RuleReaderInterface in your application or use adachsoft/agent-rule JSON-based implementation.

2. Register the tool using AiToolCallFacadeBuilder:

use AdachSoft\\AiToolCall\\PublicApi\\Builder\\AiToolCallFacadeBuilder;
use AdachSoft\\AiToolCall\\PublicApi\\Dto\\ToolCallRequestDto;
use AdachSoft\\AiToolCall\\SPI\\Collection\\ConfigMap;
use AdachSoft\\AgentRuleTool\\Tool\\AgentRuleToolFactory;
use AdachSoft\\AgentRuleContract\\Contract\\RuleReaderInterface;

$reader = /* your RuleReaderInterface implementation */;

$builder = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new AgentRuleToolFactory($reader),
    ])
    ->withToolConfigs([
        'agent_rule' => new ConfigMap([
            'max_rules' => 100,
            'max_rule_content_bytes' => 500,
            'max_payload_bytes' => 64000,
        ]),
    ]);

$facade = $builder->build();

$result = $facade->callTool(new ToolCallRequestDto('agent_rule', ['project_id' => 1]));
// or
$result = $facade->callTool(new ToolCallRequestDto('agent_rule', []));

The $result is a KeyValueMap that can be converted to an array / JSON according to adachsoft/ai-tool-call documentation.

Quick Start (agent_rule_admin)

To use the admin tool, you need an implementation of RuleWriterInterface:

use AdachSoft\\AiToolCall\\PublicApi\\Builder\\AiToolCallFacadeBuilder;
use AdachSoft\\AiToolCall\\PublicApi\\Dto\\ToolCallRequestDto;
use AdachSoft\\AiToolCall\\SPI\\Collection\\ConfigMap;
use AdachSoft\\AgentRuleTool\\Tool\\AgentRuleAdminToolFactory;
use AdachSoft\\AgentRuleContract\\Contract\\RuleWriterInterface;

$writer = /* your RuleWriterInterface implementation */;

$builder = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new AgentRuleAdminToolFactory($writer),
    ])
    ->withToolConfigs([
        'agent_rule_admin' => new ConfigMap([
            'max_rules' => 100,
            'max_rule_content_bytes' => 500, // must match read-side limit to avoid inconsistencies
            'max_payload_bytes' => 64000,
        ]),
    ]);

$facade = $builder->build();

// Example: create a rule within the configured content limit
$result = $facade->callTool(new ToolCallRequestDto('agent_rule_admin', [
    'action' => 'create',
    'rule' => [
        'id' => 'rule_1',
        'type' => 'REQUIREMENT',
        'target' => 'AGENT',
        'content' => 'Short rule content',
        'priority' => 100,
    ],
    'project_id' => null,
]));

If the content value exceeds max_rule_content_bytes, the admin tool will throw a ToolExecutionException with a message indicating that the maximum rule content size has been exceeded, and the rule will not be persisted.