koog-agents-optimization/ai.koog.agents.optimization.optimizers.ace/ACEOptimizer

ACEOptimizer

class ACEOptimizer<Input, Output, InputLabel>(playbookStoragePath: ResilientPath, onExistingPlaybook: OnExistingPlaybookAction, reflectorModel: LLModel, curatorModel: LLModel, labelExtractor: (datasetItem: TrainSetItem<Input, InputLabel>) -> String) : AgentOptimizer<Input, Output, InputLabel>

Agentic Context Engineering optimizer: improves an agent by curating an ACEPlaybook of bullet insights instead of editing its prompt directly.

For each training item the agent is run and its full trajectory captured; a reflector LLM diagnoses the trajectory into TrajectoryInsights (also tagging which existing bullets helped or hurt), and a curator LLM turns those insights into DeltaUpdates that grow and refine the playbook. The resulting playbook is injected into the agent's system prompt at run time via ACEPlaybookFeature.

Early implementation. This is a non-official re-implementation that deviates from the original ACE algorithm (https://arxiv.org/abs/2510.04618) and may underperform the paper. Validate on your own task before relying on it; closing the gap is future work.

Parameters

playbookStoragePath

Where the optimized ACEPlaybook is read from and written to.

onExistingPlaybook

How to handle a playbook already present at playbookStoragePath; see OnExistingPlaybookAction.

reflectorModel

Model used to diagnose trajectories into insights.

curatorModel

Model used to convert insights into playbook deltas.

labelExtractor

Extracts the ground-truth label string for a dataset item, fed to the reflector.

Constructors

ACEOptimizer

constructor(playbookStoragePath: ResilientPath, onExistingPlaybook: OnExistingPlaybookAction, reflectorModel: LLModel, curatorModel: LLModel, labelExtractor: (datasetItem: TrainSetItem<Input, InputLabel>) -> String)

Types

BulletTag

@Serializable

data class BulletTag(val id: String, val tag: String)

A reflector's assessment of one playbook bullet's contribution to a trajectory.

CuratorResponse

@Serializable

data class CuratorResponse(val reasoning: String, val operations: List<ACEOptimizer.RawDeltaUpdate>)

Structured curator output: the playbook mutations derived from a batch of reflector insights.

RawDeltaUpdate

@Serializable

@SerialName(value = "DeltaUpdate")

sealed class RawDeltaUpdate

A single playbook mutation as returned by the curator LLM, convertible to a DeltaUpdate via toDeltaUpdate.

ReflectorResponse

@Serializable

data class ReflectorResponse(val insights: List<ACEOptimizer.TrajectoryInsight>)

Structured reflector output: the TrajectoryInsights diagnosed from a single agent trajectory.

TrajectoryInsight

@Serializable

data class TrajectoryInsight(val reasoning: String, val errorIdentification: String, val rootCauseAnalysis: String, val correctApproach: String, val keyInsight: String, val bulletTags: List<ACEOptimizer.BulletTag>)

A single diagnosis of an agent trajectory produced by the reflector.

Functions

loadOptimizedAgent

open override fun loadOptimizedAgent(baseAgent: GraphAIAgent<Input, Output>): GraphAIAgent<Input, Output>

Loads training artifacts produced by train and applies them to the given baseAgent.

train

open suspend override fun train(session: TrainingSession<Input, Output, InputLabel>): TrainingResult

Trains the agent using the provided session, which gives access to a TrainingSession.use block where the training scope (agent, dataset, tracked execution methods) is available.