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

adachsoft / ai-agent-config-repository

Maintainers

Package info

Statistics

Security