Changelog¶

This docs was updated at: 2026-02-23

All notable changes to Agentle4j will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]¶

Tool Planning (Programmatic Tool Calling) — Batch multiple tool calls into a single declarative execution plan
Agent.Builder.enableToolPlanning() opt-in API
ToolPlanTool meta-tool registered as execute_tool_plan
Declarative plan format with steps, output_steps, and $ref references
$ref:step_id and $ref:step_id.field.nested reference syntax for data flow between steps
Topological sorting with wave-based parallel execution using virtual threads (StructuredTaskScope)
Fail-forward error handling — failed steps don't block independent work
Context window savings — intermediate results never enter the LLM context
Automatic instruction augmentation when tool planning is enabled
52 new tests across PlanReferenceResolverTest, ToolPlanExecutorTest, and ToolPlanToolTest

SupervisorAgent - Central coordinator pattern for complex task orchestration
Manages multiple worker agents with task decomposition
orchestrate() and orchestrateStream() methods
Worker agents accessed as sub-agent tools automatically
Configurable max turns for supervision loop
AgentNetwork - Decentralized peer-to-peer agent communication
Sequential discussion rounds where agents build on each other's ideas
discuss() for multi-round conversations
broadcast() for parallel message dissemination
Optional synthesizer agent to combine all contributions
NetworkResult with contribution filtering by agent/round
HierarchicalAgents - Multi-layered organizational structure
Executive → Manager → Worker hierarchy
addDepartment() to create organizational units
execute() flows tasks through the hierarchy
sendToDepartment() for direct department routing
Streaming support with executeStream()

Sub-Agents (Agent-as-Tool) - Invoke agents as tools within a parent agent's execution loop
SubAgentTool class for wrapping an Agent as a FunctionTool
Agent.Builder.addSubAgent() methods with description or config
SubAgentTool.Config for context sharing options:
- shareState(boolean) - Share custom state like userId (default: true)
- shareHistory(boolean) - Include full conversation context (default: false)
Tool naming follows invoke_[agent_snake_case_name] pattern
Prompt Management - External prompt providers for managing agent instructions
PromptProvider interface for abstracting prompt sources
FilesystemPromptProvider - Load prompts from local files
LangfusePromptProvider - Fetch prompts from Langfuse API with:
- Basic authentication support
- Configurable retry with exponential backoff
- Polymorphic response parsing (text and chat prompts)
PromptProviderException for prompt retrieval failures
Enhanced Prompt Templating - Advanced template syntax in Prompt.java
Variable interpolation: {{variable}}
Nested properties: {{user.name}}
Conditional blocks: {{#if condition}}...{{/if}}
Iteration blocks: {{#each items}}...{{/each}}

Context Management - Pluggable strategies to manage conversation context length
ContextManagementConfig - Configuration with builder pattern
SlidingWindowStrategy - Removes oldest messages when context exceeds limit
SummarizationStrategy - Summarizes older messages using an LLM
TokenCounter interface with SimpleTokenCounter (chars/4 estimation)
Retry Policies - Configurable retry with exponential backoff
RetryPolicy class for customizing retry behavior
Agent.Builder.retryPolicy() and maxRetries() methods
Automatic retry for rate limits (429) and server errors (5xx)
Exception Hierarchy - Structured error handling
AgentleException - Base exception for all library errors
ApiException - HTTP/API errors with status codes
RateLimitException, AuthenticationException, ServerException
StreamingException, GuardrailException, ToolExecutionException
Trace Correlation - Automatic trace propagation across agents
Parent trace/span IDs flow through handoffs
TelemetryContext for custom metadata and tags
Multi-agent trace correlation in observability

Renamed parsed() to outputParsed() for consistency
FunctionToolCallOutput.json() replaced with FunctionToolCallOutput.success() (explicit serialization)
Responder builder now uses baseUrl() instead of apiBaseUrl()