adachsoft/ai-agent-context-window

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

0.2.1 2026-01-29 08:28 UTC

Requires

• php: ^8.3
• adachsoft/ai-agent: 0.7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: 2.1.34
• phpunit/phpunit: ^12.4
• rector/rector: 2.3.3

MIT

• Arkadiusz Adach

• tools
• chat
• Agent
• ai
• conversation
• llm
• context-window
• tool-calls

README

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

Installation

composer require adachsoft/ai-agent-context-window

context_window Strategy

The library provides an SPI implementation:

• AdachSoft\\AiAgent\\Spi\\Conversation\\ConversationContextStrategyInterface

Strategy ID: context_window.

The strategy:

• trims history to a window of N last messages (max_messages),
• guarantees 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).

For inconsistent history (tool result without its corresponding call) an exception is thrown:

• AdachSoft\\AiAgentContextWindow\\Exception\\InconsistentToolCallingHistoryException

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 (but still validates tool-calling consistency).

Exceptions

• InvalidContextWindowConfigException when the max_messages parameter is missing, has an invalid type or is less than 1.
• InconsistentToolCallingHistoryException for inconsistent tool-calling history (tool result without matching tool call).

Static Analysis

Running PHPStan:

composer install
composer run phpstan

License

MIT