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)

1) Create ports (PublicApi facades from external libs):

ToolCallingChatFacade (e.g. Deepseek/OpenAI provider via their builders),
AiToolCallFacade (provides tool catalog and execution). 2) Build the AiAgent facade via AiAgentBuilder with config and policies. 3) Call startConversation($conversationId) once to create an empty conversation in the configured repository. 4) 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;

// 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,
    ))
    ->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 = new AskRequestDto(prompt: 'What time is it in Warsaw? Reply as HH:MM.');
$response = $facade->ask($conversationId, $request);

$finalText = $response->finalText;       // assistant final message
$history = $response->fullConversation;  // full conversation as seen by the agent

Configuring system prompt and generation parameters

Agent behaviour is configured via two fields on AgentConfigDto:

systemPrompt - high level, stable instruction injected as the first system role message in every request to adachsoft/ai-integration.
parameters - free-form array of provider-specific generation knobs forwarded 1:1 to ToolCallingChatRequestDto::$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,
    'thinkingLevel' => 'high',
],
'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.

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):
- Run from repo: php examples/agent-publicapi-quickstart/run.php "Your prompt"
- Run from installed package: php vendor/adachsoft/ai-agent/examples/agent-publicapi-quickstart/run.php "Your prompt"
Interactive chat (stateful over a single conversationId):
- Run from repo: php examples/agent-publicapi-chat/run.php
- Run from installed package: php vendor/adachsoft/ai-agent/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): void
AiAgentFacadeInterface::ask(string $conversationId, AskRequestDto $request): AskResponseDto

AskResponseDto contains:

fullConversation (ChatMessageDtoCollection) - full conversation as seen by the agent after the turn,
tokensUsed (TokensUsageDto: promptTokens, completionTokens, totalTokens),
status (enum value describing orchestration outcome),
finalText (string|null) - final assistant text for this turn.

SPI: Chat turn resolution

When the underlying provider returns an ambiguous chat turn (both finalText and at least one toolCall), 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 - use finalText, ignore toolCalls.
prefer_tool_calls - ignore finalText, continue with tool execution.
error_on_conflict - treat the situation as a domain error.

Example:

$facade = (new AiAgentBuilder())
    ->withPorts($ports)
    ->withAgentConfig($config)
    ->withPolicies($policies)
    ->withChatTurnResolutionMode('prefer_final_text')
    ->build();

Custom SPI strategy

For full control you can implement the SPI:

Interface: AdachSoft\\AiAgent\\Spi\\Conversation\\ChatTurnResolutionStrategyInterface
Method: public function decide(ChatTurnResult $turn): string
Expected return values:
- 'use_final_text'
- 'use_tool_calls'
- 'error'

use AdachSoft\\AiAgent\\Spi\\Conversation\\ChatTurnResolutionStrategyInterface as SpiStrategy;

final class MyResolutionStrategy implements SpiStrategy
{
    public function decide(ChatTurnResult $turn): string
    {
        // your custom policy here
        return 'use_tool_calls';
    }
}

$facade = (new AiAgentBuilder())
    ->withPorts($ports)
    ->withAgentConfig($config)
    ->withPolicies($policies)
    ->withSpiChatTurnResolutionStrategy(new MyResolutionStrategy())
    ->build();

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 conversationId and appends only new messages via ConversationRepositoryInterface.
Ports only: integrates via PublicApi facades (no HTTP details in this lib).
Collections: uses adachsoft/collection; no public arrays in DTOs.

Changelog

See CHANGELOG.md. Source of truth is changelog.json (generated via adachsoft/changelog-linter).

License

MIT (see composer.json).

adachsoft / ai-agent

Maintainers

Details