README

Framework-agnostic library for storing and using AI agent configuration for agents built with the adachsoft/ai-agent runtime.

This package provides:

• a model of agent configuration (VO/DTO/Collection/Exception),
• SPI repository layer with full CRUD for agent configurations and system prompts,
• a Public API for creating AiAgentFacadeInterface instances based on configuration loaded from repositories.

Requirements

• PHP: ^8.3
• adachsoft/collection: ^3.0
• adachsoft/ai-agent: ^0.8
• adachsoft/ai-integration: ^0.6.1
• adachsoft/ai-tool-call: ^2.0

Installation

composer require adachsoft/ai-agent-config-repository

Package structure

Root namespace:

• AdachSoft\AiAgentConfigRepository\...

Directory layout:

• src/AiAgentConfigRepository/PublicApi
  • Vo – value objects (agent, prompt, tool, tool group identifiers)
  • Dto – agent configuration DTO and policies DTO
  • Collection – VO collections based on AbstractImmutableCollection
  • Exception – domain exceptions exposed by the Public API
  • AiAgentFromConfigFactoryInterface – factory creating AiAgentFacadeInterface from config
• src/AiAgentConfigRepository/SPI
  • Repository – repository interfaces for agent configs and system prompts (full CRUD)
  • Mapper – mapper interface from agent definition to DTOs from adachsoft/ai-agent
• src/AiAgentConfigRepository/Infrastructure
  • Repository/InMemory – in-memory reference implementations of repositories
  • Factory – implementation of AiAgentFromConfigFactoryInterface

Public API

Value Objects (VO)

• AdachSoft\AiAgentConfigRepository\PublicApi\Vo\AgentId
• AdachSoft\AiAgentConfigRepository\PublicApi\Vo\PromptId
• AdachSoft\AiAgentConfigRepository\PublicApi\Vo\ToolId
• AdachSoft\AiAgentConfigRepository\PublicApi\Vo\ToolGroupId

Each VO is a simple readonly wrapper around a string (public string $value).

DTOs

• AdachSoft\AiAgentConfigRepository\PublicApi\Dto\AgentPoliciesDto
  • retry / backoff / limits / timeouts / trimming / tools-related policies
• AdachSoft\AiAgentConfigRepository\PublicApi\Dto\AgentDefinitionDto
  • provider-agnostic, complete agent definition that contains:
    • identifier, name, description,
    • provider id and model id,
    • prompt id and system prompt text,
    • model parameters,
    • timeout in seconds,
    • allowed tool ids / tool group ids,
    • agent policies (AgentPoliciesDto),
    • conversation context strategy id and parameters.

Collections

• AdachSoft\AiAgentConfigRepository\PublicApi\Collection\ToolIdCollection
• AdachSoft\AiAgentConfigRepository\PublicApi\Collection\ToolGroupIdCollection

Both collections extend AdachSoft\Collection\AbstractImmutableCollection and are strongly typed to ToolId and ToolGroupId respectively.

Exceptions

Namespace:

AdachSoft\AiAgentConfigRepository\PublicApi\Exception

Defined exceptions:

• AgentNotFoundException
• AgentAlreadyExistsException
• SystemPromptNotFoundException
• SystemPromptAlreadyExistsException
• AgentRuntimeBuildFailedException

These exceptions are used by the Public API and SPI implementations to signal consistent error conditions.

SPI layer

AgentConfigRepositoryInterface

AdachSoft\AiAgentConfigRepository\SPI\Repository\AgentConfigRepositoryInterface

SPI repository contract for agent configuration with full CRUD, operating on AgentDefinitionDto instances identified by AgentId.

SystemPromptRepositoryInterface

AdachSoft\AiAgentConfigRepository\SPI\Repository\SystemPromptRepositoryInterface

SPI repository contract for system prompts with full CRUD, operating on prompt contents identified by PromptId.

AgentDefinitionMapperInterface

AdachSoft\AiAgentConfigRepository\SPI\Mapper\AgentDefinitionMapperInterface

Mapper responsible for transforming an AgentDefinitionDto into the DTOs required by the adachsoft/ai-agent runtime:

• AgentConfigDto
• PortsConfigDto
• PoliciesConfigDto

It also wires the ports (ToolCallingChatFacadeInterface, AiToolCallFacadeInterface).

In-memory implementations

The library ships with reference, in-memory repository implementations:

• AdachSoft\AiAgentConfigRepository\Infrastructure\Repository\InMemory\InMemoryAgentConfigRepository
  • implements AgentConfigRepositoryInterface
  • stores AgentDefinitionDto instances in an in-memory array
• AdachSoft\AiAgentConfigRepository\Infrastructure\Repository\InMemory\InMemorySystemPromptRepository
  • implements SystemPromptRepositoryInterface
  • stores a PromptId => systemPrompt map in memory

These are intended as reference implementations and for tests / simple setups. You are expected to provide your own persistence-backed repositories (database, filesystem, etc.) in your application.

Agent factory from configuration

Contract

AdachSoft\AiAgentConfigRepository\PublicApi\AiAgentFromConfigFactoryInterface

Public API for creating AiAgentFacadeInterface instances based on AgentId.

Method:

public function createById(AgentId $agentId, ?PublicEventPublisherInterface $publicEventPublisher = null): AiAgentFacadeInterface;

Exceptions:

• AgentNotFoundException – when configuration for the given agent id does not exist,
• AgentRuntimeBuildFailedException – when the runtime agent cannot be built (e.g. missing prompt, failure in AiAgentBuilder).

Implementation

AdachSoft\AiAgentConfigRepository\Infrastructure\Factory\AiAgentFromConfigFactory

The factory uses:

• AgentConfigRepositoryInterface – to load AgentDefinitionDto,
• SystemPromptRepositoryInterface – to load the system prompt text,
• AgentDefinitionMapperInterface – to map the definition to adachsoft/ai-agent DTOs,
• ToolCallingChatFacadeInterface and AiToolCallFacadeInterface – provided ports,
• AiAgentBuilder – to build the final AiAgentFacadeInterface instance.

This keeps all mapping from configuration to runtime agent in a single place.

Usage example

use AdachSoft\AiAgentConfigRepository\Infrastructure\Factory\AiAgentFromConfigFactory;
use AdachSoft\AiAgentConfigRepository\Infrastructure\Repository\InMemory\InMemoryAgentConfigRepository;
use AdachSoft\AiAgentConfigRepository\Infrastructure\Repository\InMemory\InMemorySystemPromptRepository;
use AdachSoft\AiAgentConfigRepository\PublicApi\Vo\AgentId;
use AdachSoft\AiAgentConfigRepository\SPI\Mapper\AgentDefinitionMapperInterface;
use AdachSoft\AiIntegration\PublicApi\ToolCalling\ToolCallingChatFacadeInterface;
use AdachSoft\AiToolCall\PublicApi\AiToolCallFacadeInterface;

$agentConfigRepository = new InMemoryAgentConfigRepository();
$systemPromptRepository = new InMemorySystemPromptRepository();

$mapper = /* your implementation of AgentDefinitionMapperInterface */;
$toolCallingChatFacade = /* your implementation of ToolCallingChatFacadeInterface */;
$aiToolCallFacade = /* your implementation of AiToolCallFacadeInterface */;

$factory = new AiAgentFromConfigFactory(
    $agentConfigRepository,
    $systemPromptRepository,
    $mapper,
    $toolCallingChatFacade,
    $aiToolCallFacade,
);

$agentId = new AgentId('my-agent');

$agentFacade = $factory->createById($agentId);

$response = $agentFacade->chat('Hello!');

Tests and quality

The project is configured to work with:

• PHPUnit – unit tests in the tests/ directory,
• PHPStan – static analysis configured via phpstan.neon (covers src/ and tests/),
• Rector – automated refactoring rules configured in rector.php.

Run tests:

vendor/bin/phpunit

Run PHPStan:

vendor/bin/phpstan analyse src tests

Run Rector in dry-run mode:

vendor/bin/rector process src tests --dry-run