AgentGrad 2026: Arsitektur Sequential Intervention, Agent-Level Supervision, dan Semantic Textual Gradient Abstraction pada Multi-Agent Systems

// AgentGrad Multi-Agent Prompt Optimization Engine (TypeScript Reference Architecture)
// Berdasarkan Arsitektur Riset Chu et al. (arXiv:2609.08572, September 2026)
// Mengimplementasikan Sequential Intervention, Agent-Level Supervision, dan Semantic Gradient Abstraction

export interface AgentNode {
  id: string;
  name: string;
  role: string;
  currentPrompt: string;
}

export interface ExecutionStep {
  agentId: string;
  inputContext: string;
  output: string;
  hadIntervention: boolean;
}

export interface SystemTrajectory {
  input: string;
  groundTruth: string;
  steps: ExecutionStep[];
  finalOutput: string;
  reward: number; // 0.0 sampai 1.0
}

export interface SampleGradient {
  agentId: string;
  sampleInput: string;
  failedOutput: string;
  correctedOutput: string;
  textualGradient: string;
}

export interface SemanticMinibatch {
  agentId: string;
  clusterId: string;
  generalizedGradient: string;
  sampleGradients: SampleGradient[];
  influenceWeight: number; // Ukuran cluster |D_j^n|
}

/**
 * 1. Sequential Intervention Engine
 * Menguji intervensi satu demi satu dalam urutan eksekusi terbalik (Reverse Order)
 * untuk mengisolasi agen penyebab tunggal (Credit Assignment).
 */
export class SequentialInterventionRunner {
  constructor(
    private agents: AgentNode[],
    private rewardFn: (output: string, target: string) => number,
    private llmCaller: (systemPrompt: string, userPrompt: string) => Promise<string>
  ) {}

  public async evaluateWithIntervention(
    input: string,
    groundTruth: string,
    interveneAgentId?: string,
    hintText?: string
  ): Promise<SystemTrajectory> {
    const steps: ExecutionStep[] = [];
    let currentFlowContext = input;

    for (const agent of this.agents) {
      let promptToUse = agent.currentPrompt;
      const isIntervening = agent.id === interveneAgentId;

      if (isIntervening && hintText) {
        // Injeksi Hint supervisi hanya pada tahap pelatihan intervensi
        promptToUse += `\n\n[SUPERVISORY_INTERVENTION_HINT]\nTarget Output Expectation: ${hintText}\nRefine your output to satisfy these constraints strictly.\n[/SUPERVISORY_INTERVENTION_HINT]`;
      }

      const agentOutput = await this.llmCaller(promptToUse, currentFlowContext);
      steps.push({
        agentId: agent.id,
        inputContext: currentFlowContext,
        output: agentOutput,
        hadIntervention: isIntervening,
      });

      // Alirkan intermediate output ke agen berikutnya
      currentFlowContext = `Input: ${input}\nIntermediate State from ${agent.name}: ${agentOutput}`;
    }

    const finalOutput = steps[steps.length - 1].output;
    const reward = this.rewardFn(finalOutput, groundTruth);

    return { input, groundTruth, steps, finalOutput, reward };
  }

  /**
   * Reverse Execution Scan untuk isolasi Target Prompt (Equation 3):
   * T^n = { (x_i, y_i) in F^{n+1} | r(Pi^{(n, H)}(x_i), y_i) == r_max }
   */
  public async isolateTargetAgent(
    failedSample: { input: string; groundTruth: string },
    hint: string
  ): Promise<{ targetAgentId: string; correctedOutput: string; failedOutput: string; sampleInput: string } | null> {
    // Jalankan dari agen terakhir mundur ke agen pertama
    for (let idx = this.agents.length - 1; idx >= 0; idx--) {
      const candidateAgent = this.agents[idx];
      const intervenedTrajectory = await this.evaluateWithIntervention(
        failedSample.input,
        failedSample.groundTruth,
        candidateAgent.id,
        hint
      );

      if (intervenedTrajectory.reward >= 1.0) {
        const step = intervenedTrajectory.steps.find(s => s.agentId === candidateAgent.id)!;
        // Dapatkan failed output awal tanpa intervensi
        const baselineTrajectory = await this.evaluateWithIntervention(
          failedSample.input,
          failedSample.groundTruth
        );
        const baseStep = baselineTrajectory.steps.find(s => s.agentId === candidateAgent.id)!;

        return {
          targetAgentId: candidateAgent.id,
          correctedOutput: step.output,
          failedOutput: baseStep.output,
          sampleInput: step.inputContext,
        };
      }
    }

    // Jika intervensi tidak mampu menyelesaikan (hard instance)
    return null;
  }
}

/**
 * 2. Semantic Textual Gradient Abstraction (STGA) Engine
 * Mengelompokkan gradien per-sampel ke dalam cluster semantik dan mengabstraksikannya
 * menjadi generalized gradient tanpa pencampuran failure mode acak.
 */
export class SemanticGradientAggregator {
  constructor(private llmCaller: (systemPrompt: string, userPrompt: string) => Promise<string>) {}

  public async extractSampleGradient(
    agentPrompt: string,
    sampleInput: string,
    failedOutput: string,
    correctedOutput: string
  ): Promise<string> {
    const prompt = `Compare the following failed output and corrected output under the same prompt and input context:
Agent Prompt: ${agentPrompt}
Input Context: ${sampleInput}
[FAILED OUTPUT]: ${failedOutput}
[CORRECTED OUTPUT]: ${correctedOutput}

Extract a concise, targeted natural-language textual gradient explaining precisely what constraint, behavior, or format the agent prompt failed to specify.`;

    return await this.llmCaller('You are an expert Textual Gradient Extractor (LLM_Nabla).', prompt);
  }

  public async clusterAndAbstract(
    agentId: string,
    sampleGradients: SampleGradient[]
  ): Promise<SemanticMinibatch[]> {
    if (sampleGradients.length === 0) return [];

    // Sintesis pengelompokan semantik via LLM Aggregator
    const clusteringPrompt = `Group the following ${sampleGradients.length} sample-level textual gradients into semantic clusters based on shared corrective patterns.
Do NOT mix unrelated error modes (e.g. format issues vs factual omissions).
Gradients:
${sampleGradients.map((g, i) => `[${i}] ${g.textualGradient}`).join('\n')}

Return JSON array format:
[
  {
    "clusterId": "cluster-1",
    "indices": [0, 1, 3],
    "generalizedGradient": "Synthesized generalized corrective direction covering all clustered items."
  }
]`;

    const rawResponse = await this.llmCaller('You are a Semantic Textual Gradient Aggregator.', clusteringPrompt);
    const parsed = JSON.parse(rawResponse.replace(/```json|```/g, '').trim());

    return parsed.map((item: any) => ({
      agentId,
      clusterId: item.clusterId,
      generalizedGradient: item.generalizedGradient,
      sampleGradients: item.indices.map((idx: number) => sampleGradients[idx]),
      influenceWeight: item.indices.length,
    }));
  }
}

/**
 * 3. Two-Tier Verification & Prompt Update Gate
 * Menerapkan candidate prompt baru dan memvalidasi perbaikan pada Minibatch lokal
 * sebelum mengevaluasi held-out validation set.
 */
export class PromptOptimizerPipeline {
  public static async optimizeCycle(
    agents: AgentNode[],
    minibatches: SemanticMinibatch[],
    validateMinibatch: (agentId: string, newPrompt: string, mb: SemanticMinibatch) => Promise<boolean>,
    validateHeldOut: (agents: AgentNode[]) => Promise<boolean>,
    optimizerLLM: (currentPrompt: string, generalizedGrad: string) => Promise<string>
  ): Promise<{ updatedAgents: AgentNode[]; appliedCount: number }> {
    // Urutkan dari pengaruh cluster terbesar (|D_j^n| descending)
    const sortedBatches = [...minibatches].sort((a, b) => b.influenceWeight - a.influenceWeight);
    let appliedCount = 0;

    for (const batch of sortedBatches) {
      const agent = agents.find(a => a.id === batch.agentId);
      if (!agent) continue;

      const candidatePrompt = await optimizerLLM(agent.currentPrompt, batch.generalizedGradient);

      // Gate 1: Evaluasi perbaikan pada semantic minibatch
      const passesMinibatch = await validateMinibatch(agent.id, candidatePrompt, batch);
      if (!passesMinibatch) continue;

      // Gate 2: Evaluasi pada held-out validation set untuk mencegah over-fitting
      const trialAgents = agents.map(a => a.id === agent.id ? { ...a, currentPrompt: candidatePrompt } : a);
      const passesValidation = await validateHeldOut(trialAgents);

      if (passesValidation) {
        agent.currentPrompt = candidatePrompt;
        appliedCount++;
      }
    }

    return { updatedAgents: agents, appliedCount };
  }
}