Search by

adachsoft / ai-agent-context-window

Arkadiusz Adach

Context window strategy for adachsoft/ai-agent: sliding window with tool-call aware trimming for AI conversation history.

Package info

gitlab.com/a.adach/ai-agent-context-window

Issues

pkg:composer/adachsoft/ai-agent-context-window

Statistics

Installs: 60

Dependents: 0

Suggesters: 0

Stars: 0

v0.4.0 2026-11-13 20:58 UTC

This package is auto-updated.

Last update: 2026-11-13 20:02:11 UTC


README

Library extending adachsoft/ai-agent with a context window conversation trimming strategy.

Installation

composer require adachsoft/ai-agent-context-window

This package requires adachsoft/ai-agent ^0.13 and uses the shared adachsoft/ai-conversation-model message types.

context_window Strategy

The library provides an SPI implementation:

  • AdachSoft\AiAgent\Spi\Conversation\ConversationContextStrategyInterface

Strategy ID: context_window.

The strategy accepts and returns a shared-model AdachSoft\AiConversationModel\Message\Collection\ChatMessageDtoCollection. Each item is an AdachSoft\AiConversationModel\Message\ChatMessageDto, with its message ID represented by ChatMessageIdVo, role by ChatRoleEnum, content by ContentPartCollection, tool calls by ToolCallDtoCollection, and tool results by ToolResultDtoCollection.

The strategy:

  • trims history to a window of N last messages (max_messages),
  • preserves tool-calling consistency in the returned context:
    • if tool results (toolResults) are present in the window, the strategy automatically extends the window backwards to include their corresponding calls (toolCalls),
    • when needed, the limit is treated as a soft limit (more messages than max_messages are returned).

ChatMessageDtoCollection validates conversation integrity when a collection is created. The strategy creates a new validated collection after trimming.

Usage with AiAgentBuilder

use AdachSoft\AiAgent\PublicApi\Builder\AiAgentBuilder;
use AdachSoft\AiAgent\PublicApi\Dto\AgentConfigDto;
use AdachSoft\AiAgentContextWindow\Conversation\Strategy\ContextWindowConversationContextStrategy;

$strategy = new ContextWindowConversationContextStrategy();

$builder = new AiAgentBuilder();

$facade = $builder
    ->withPorts($ports)               // PortsConfigDto
    ->withAgentConfig(new AgentConfigDto(
        name: 'MyAgent',
        description: 'Demo agent with context window',
        providerId: 'deepseek',
        modelId: 'deepseek-chat',
        conversationContextStrategyId: 'context_window',
        conversationContextStrategyParams: [
            'max_messages' => 30,
        ],
    ))
    ->withPolicies($policies)         // PoliciesConfigDto
    ->withSpiConversationContextStrategy($strategy)
    ->build();

Configuration

Configuration is provided via the conversationContextStrategyParams bag on AgentConfigDto and read by ContextWindowConversationContextStrategy.

Supported parameters:

  • max_messages (int, required for trimming)
    • soft limit for the number of recent messages kept in the context window,
    • must be an integer greater than or equal to 1.

Example:

use AdachSoft\AiAgent\PublicApi\Dto\AgentConfigDto;

$agentConfig = new AgentConfigDto(
    name: 'MyAgent',
    description: 'Demo agent with context window',
    providerId: 'deepseek',
    modelId: 'deepseek-chat',
    conversationContextStrategyId: 'context_window',
    conversationContextStrategyParams: [
        'max_messages' => 50,
    ],
);

If max_messages is not provided, the strategy returns the full conversation without trimming.

Exceptions

  • InvalidContextWindowConfigException when the max_messages parameter has an invalid type or is less than 1.

Static Analysis

Running PHPStan:

composer install
composer run phpstan

License

MIT