adachsoft / ai-agent
Stateless AI Agent Orchestrator Library for tool-calling chats.
Requires
- php: ^8.3
- adachsoft/ai-conversation-model: ^0.2
- adachsoft/ai-integration: ^0.10.2
- adachsoft/ai-tool-call: ^2.2
- adachsoft/collection: ^3.0
- adachsoft/console-io: ^0.2
Requires (Dev)
- adachsoft/changelog-linter: ^0.3.0
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.89
- phpstan/phpstan: ^2.1.50
- phpunit/phpunit: ^12.4
- rector/rector: ^2.4
- twig/twig: ^3.0
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.13.3
- v0.13.2
- v0.13.1
- v0.13.0
- v0.12.2
- v0.12.1
- v0.12.0
- v0.11.2
- v0.11.1
- v0.11.0
- v0.10.0
- v0.9.1
- v0.9.0
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.4
- v0.5.3
- v0.5.2
- v0.5.1
- v0.5.0
- v0.4.1
- v0.4.0
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1.0
- dev-task965-cost
- dev-task061
- dev-task015
- dev-task047
This package is auto-updated.
Last update: 2026-11-17 07:31:40 UTC
README
Stateful AI Agent Orchestrator Library for tool-calling chats.
- PHP: >= 8.3
- Namespace:
AdachSoft\\AiAgent\\
Overview
This library orchestrates tool-calling chats in stateful mode. The client identifies a conversation by conversationId, the library owns and persists full conversation history behind a ConversationRepositoryInterface, and each ask() call executes a single agent turn over the stored history.
High-level responsibilities:
- maintain conversation history and correlate messages with tool calls,
- control the tool-calling loop under retry and budget policies,
- integrate exclusively with external PublicApi facades for chat and tools (no HTTP transport in this library),
- expose a small, stable PublicApi facade for starting conversations and executing turns.
See detailed docs:
docs/PROJECT_OVERVIEW_AI_AGENT.md(EN)docs/PRZEGLAD_PROJEKTU_AI_AGENT.md(PL)
Installation
Install via Composer:
composer require adachsoft/ai-agent
This library relies on external PublicApi facades for chat and tools (installed by you):
adachsoft/ai-integration(ToolCallingChatFacade)adachsoft/ai-tool-call(AiToolCallFacade)
Quick Start (Stateful)
- Create ports (PublicApi facades from external libs):
- ToolCallingChatFacade (e.g. Deepseek/OpenAI provider via their builders),
- AiToolCallFacade (provides tool catalog and execution).
- Build the AiAgent facade via
AiAgentBuilderwith config and policies. - Call
startConversation($conversationId)once to create an empty conversation in the configured repository. - For each user turn call
ask($conversationId, AskRequestDto)and persist nothing yourself – the library appends new messages internally.
Minimal Example (stateful)
use AdachSoft\AiAgent\PublicApi\Builder\AiAgentBuilder;
use AdachSoft\AiAgent\PublicApi\Dto\AgentConfigDto;
use AdachSoft\AiAgent\PublicApi\Dto\AskRequestDto;
use AdachSoft\AiAgent\PublicApi\Dto\Collection\ToolIdCollection;
use AdachSoft\AiAgent\PublicApi\Dto\PoliciesConfigDto;
use AdachSoft\AiAgent\PublicApi\Dto\PortsConfigDto;
use AdachSoft\AiAgent\PublicApi\Vo\ToolId;
use AdachSoft\AiAgent\Spi\Conversation\ConversationRepositoryInterface as SpiConversationRepositoryInterface;
// 1) Create external facades (using your provider credentials)
$toolCalling = /* ToolCallingChatFacadeInterface from adachsoft/ai-integration */;
$aiTools = /* AiToolCallFacadeInterface from adachsoft/ai-tool-call */;
$ports = new PortsConfigDto(
toolCallingChatFacade: $toolCalling,
aiToolCallFacade: $aiTools,
);
// 2) Build AiAgent facade in stateful mode
$facade = (new AiAgentBuilder())
->withPorts($ports)
->withAgentConfig(new AgentConfigDto(
name: 'MyAgent',
description: 'Demo stateful agent',
providerId: 'deepseek',
modelId: 'deepseek-chat',
systemPrompt: 'You are a helpful assistant.',
parameters: [
'temperature' => 0.2,
'max_tokens' => 1024,
],
timeoutSeconds: 60,
tools: new ToolIdCollection([new ToolId('current_datetime')]),
))
->withPolicies(new PoliciesConfigDto(
maxSteps: 6,
maxToolCallsPerTurn: 2,
maxDurationSeconds: 60,
))
// Optional: provide your own SPI-backed repository implementation
// ->withSpiConversationRepository($mySpiRepository)
->build();
$conversationId = 'example-conversation-1';
// 3) Start a new empty conversation once
try {
$facade->startConversation($conversationId);
} catch (\AdachSoft\AiAgent\PublicApi\Exception\ConversationAlreadyExistsPublicApiException $e) {
// conversation already exists - reuse it
}
// 4) Ask a question (one stateful turn)
$request = AskRequestDto::text('What time is it in Warsaw? Reply as HH:MM.');
$response = $facade->ask($conversationId, $request);
$finalText = $response->finalText; // assistant final text
$finalContent = $response->finalContent; // assistant final content parts (text and/or media)
$history = $response->fullConversation; // full conversation as seen by the agent
Multimodal questions
AskRequestDto carries a ContentPartCollection from adachsoft/ai-conversation-model, so a user message can contain images or other media next to text (the provider must support them):
use AdachSoft\AiConversationModel\Content\Collection\ContentPartCollection;
use AdachSoft\AiConversationModel\Content\MediaContentPartDto;
use AdachSoft\AiConversationModel\Content\MediaSourceEnum;
use AdachSoft\AiConversationModel\Content\MimeTypeVo;
use AdachSoft\AiConversationModel\Content\TextContentPartDto;
$response = $facade->ask($conversationId, new AskRequestDto(new ContentPartCollection([
new TextContentPartDto('What is on this picture?'),
new MediaContentPartDto(new MimeTypeVo('image/png'), MediaSourceEnum::Base64, base64_encode($png)),
])));
Conversation model
Conversation messages, tool calls, tool results and token usage use the shared types of adachsoft/ai-conversation-model (ChatMessageDto, ChatMessageDtoCollection, ToolCallDto, ToolResultDto, TokenUsageDto) in the PublicApi, the SPI and the domain – the same model adachsoft/ai-integration uses, so nothing is mapped between layers.
- A
ChatMessageDtoCollectionvalidates conversation integrity on construction (unique message ids, chronological order, every tool call answered before the conversation continues). - Tool results are content parts; results of
adachsoft/ai-tool-calltools are stored as a JSON text part, followed by one base64 media part per item ofToolCallResultDto::$media(ai-tool-call 2.2+, e.g. an image the tool read). Media the conversation model rejects (invalid MIME type) end the call withToolExecutionDomainException. - Before a new user message,
ask()answers tool calls left without results at the end of the history (an interrupted run) with a synthetic "interrupted" result and persists it.
Conversation Repository Configuration
By default the builder uses an in-memory repository (InMemoryConversationRepository). To provide a persistent implementation:
- Implement
AdachSoft\AiAgent\Spi\Conversation\ConversationRepositoryInterface - Register it via
AiAgentBuilder::withSpiConversationRepository(SpiConversationRepositoryInterface $repository)
The builder automatically wraps your SPI implementation with SpiBackedConversationRepository, which only translates SPI exceptions into domain exceptions.
load()returns aChatMessageDtoCollection. When stored histories may be invalid (legacy data, manual edits), rebuild them withAdachSoft\AiAgent\Spi\Conversation\ConversationHistoryRepairer::repair()– it makes ids unique, timestamps non-decreasing, drops orphaned or duplicate tool results and answers tool calls left without results.append()receives aChatMessageDeltaCollection– the new messages in order. A delta is not validated on its own (its tool results answer calls stored earlier); the stored history followed by the delta is a valid conversation.
The facade methods (startConversation, ask, getRawConversation, listConversationIds, deleteConversation) work with any repository backend.
Conversation Management
The AiAgentFacadeInterface now provides dedicated methods for managing conversations:
getRawConversation(string $conversationId): ChatMessageDtoCollection– returns the complete raw history without applying any context trimming strategy (useful for auditing, export, debugging or admin panels).listConversationIds(): ConversationIdDtoCollection– returns all known conversation identifiers (empty collection when none exist).deleteConversation(string $conversationId): void– permanently deletes a conversation and its entire history. ThrowsConversationNotFoundPublicApiExceptionwhen the conversation does not exist.
These methods work with any implementation of ConversationRepositoryInterface (in-memory or SPI-backed).
Example:
$rawHistory = $facade->getRawConversation($conversationId);
$allIds = $facade->listConversationIds();
foreach ($allIds as $id) {
echo "Conversation: $id\n";
}
// Delete when no longer needed
$facade->deleteConversation('old-conversation-123');
Configuring system prompt and generation parameters
Agent behaviour is configured via two fields on AgentConfigDto:
systemPrompt– high level, stable instruction injected as the firstsystemrole message in every request toadachsoft/ai-integration.parameters– free-form array of provider-specific generation knobs forwarded 1:1 toToolCallingChatRequestDto::$parameters(no renaming or filtering).
Examples of parameters values:
- OpenAI-style:
['temperature' => 0.7, 'max_tokens' => 200, 'top_p' => 0.9, 'presence_penalty' => 0.6, 'frequency_penalty' => 0.3] - Gemini-style:
['temperature' => 0.5, 'thinkingConfig' => ['includeThoughts' => false], 'maxOutputTokens' => 8192]
You are responsible for choosing parameter names that match the selected provider (providerId, modelId). The agent library treats this array as opaque data and passes it straight to adachsoft/ai-integration.
Excess tool calls per turn
PoliciesConfigDto::$rejectExcessToolCalls (default false) controls what happens when the model requests more tool calls than maxToolCallsPerTurn:
- When disabled (default), the library executes only the allowed calls and returns a
Limitedresult with thetool_calls_per_turnreason. - When enabled, calls within the limit are executed, excess calls receive correlated error results without being executed, and the run continues to the next turn.
Examples
Runnable examples are provided in the examples/ directory. Each example has its own folder with run.php and README.md.
- Quickstart (single stateful turn):
php examples/agent-publicapi-quickstart/run.php "Your prompt" - Interactive chat (stateful over a single conversationId):
php examples/agent-publicapi-chat/run.php
Note: bin/ scripts are thin wrappers that redirect to example entrypoints.
Environment variables:
DEEPSEEK_API_KEY
API Highlights
AiAgentFacadeInterface::startConversation(string $conversationId): voidAiAgentFacadeInterface::ask(string $conversationId, AskRequestDto $request): AskResponseDtoAiAgentFacadeInterface::getRawConversation(string $conversationId): ChatMessageDtoCollectionAiAgentFacadeInterface::listConversationIds(): ConversationIdDtoCollectionAiAgentFacadeInterface::deleteConversation(string $conversationId): voidAiAgentFacadeInterface::getConversationContext(string $conversationId): ChatMessageDtoCollection(applies configured trimming strategy)AiAgentBuilder::withSpiConversationRepository(SpiConversationRepositoryInterface $repository): selfAiAgentBuilder::withSpiConversationContextStrategy(ConversationContextStrategyInterface $strategy): self– the strategy receives and returns aChatMessageDtoCollection; a strategy that trims history can pass its result throughConversationHistoryRepairerto drop results cut off from their calls.
AskResponseDto contains:
fullConversation(ChatMessageDtoCollection) – full conversation as seen by the agent after the turn,tokensUsed(TokenUsageDto:inputTokens,outputTokens,totalTokens,details),status(AskStatusEnum) – orchestration outcome for the turn:Completed,Limited, orFailed,finalText(string|null) – final assistant text for this turn,finalContent(ContentPartCollection|null) – final assistant content (text and media parts) when the turn completed,limitInfo(LimitInfoDto|null) – present only whenstatusisLimited; contains the limit reason (e.g. steps, tool calls per turn, duration), execution metrics (executedSteps,executedToolCalls,elapsedSeconds) and the configured limits fromPoliciesConfigDto.
SPI: Chat turn resolution
When the underlying provider returns an ambiguous chat turn (both content and at least one tool call), the library uses a strategy to decide how to interpret the result.
Built-in strategies
You can select one of the built-in domain strategies via AiAgentBuilder::withChatTurnResolutionMode(string $mode):
prefer_final_text– usefinalText, ignoretoolCalls.prefer_tool_calls– ignorefinalText, continue with tool execution.error_on_conflict– treat the situation as a domain error.
Custom SPI strategy
For full control you can implement the SPI:
- Interface:
AdachSoft\AiAgent\Spi\Conversation\ChatTurnResolutionStrategyInterface - Method:
public function decide(ChatTurnResultDto $turn): string– the DTO carriescontent(ContentPartCollection),toolCalls(ToolCallDtoCollection),tokenUsageandmetadata, plusfinalText() - Expected return values:
'use_final_text','use_tool_calls','error'
Register your SPI strategy via the builder (example omitted for brevity – see full docs).
Internally the library adapts the SPI decision to a domain enum and uses it inside the orchestrator; the public API of AiAgentFacadeInterface remains unchanged.
Design Notes
- Stateful: the library owns conversation history keyed by
conversationIdand appends only new messages viaConversationRepositoryInterface. - Ports only: integrates via PublicApi facades (no HTTP details in this lib).
- Collections: uses
adachsoft/collection; no public arrays in DTOs. New collections (ConversationIdCollection,ConversationIdDtoCollection) follow the modernisValidItem()pattern. - Shared conversation model: PublicApi, SPI and domain use
adachsoft/ai-conversation-model; the builder accepts only SPI interfaces for repositories and strategies.
Changelog
See CHANGELOG.md. Source of truth is changelog.json (generated via adachsoft/changelog-linter).
License
MIT (see composer.json).