refactor(agents): Introduce Declarative Agent Framework (#9778)

2026-05-14 05:42:54 -07:00 · 2025-09-30 17:00:54 -04:00
parent 6695c32aa2
commit 794d92a79d
14 changed files with 2746 additions and 0 deletions
@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { templateString } from './utils.js';
+import type { AgentInputs } from './types.js';
+
+describe('templateString', () => {
+  it('should replace a single placeholder with a string value', () => {
+    const template = 'Hello, ${name}!';
+    const inputs: AgentInputs = { name: 'World' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('Hello, World!');
+  });
+
+  it('should replace multiple unique placeholders', () => {
+    const template = 'User: ${user}, Role: ${role}';
+    const inputs: AgentInputs = { user: 'Alex', role: 'Admin' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('User: Alex, Role: Admin');
+  });
+
+  it('should replace multiple instances of the same placeholder', () => {
+    const template = '${greeting}, ${user}. Welcome, ${user}!';
+    const inputs: AgentInputs = { greeting: 'Hi', user: 'Sam' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('Hi, Sam. Welcome, Sam!');
+  });
+
+  it('should handle various data types for input values', () => {
+    const template =
+      'Name: ${name}, Age: ${age}, Active: ${isActive}, Plan: ${plan}, Score: ${score}';
+    const inputs: AgentInputs = {
+      name: 'Jo',
+      age: 30,
+      isActive: true,
+      plan: null,
+      score: undefined,
+    };
+    const result = templateString(template, inputs);
+    // All values are converted to their string representations
+    expect(result).toBe(
+      'Name: Jo, Age: 30, Active: true, Plan: null, Score: undefined',
+    );
+  });
+
+  it('should return the original string if no placeholders are present', () => {
+    const template = 'This is a plain string with no placeholders.';
+    const inputs: AgentInputs = { key: 'value' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('This is a plain string with no placeholders.');
+  });
+
+  it('should correctly handle an empty template string', () => {
+    const template = '';
+    const inputs: AgentInputs = { key: 'value' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('');
+  });
+
+  it('should ignore extra keys in the inputs object that are not in the template', () => {
+    const template = 'Hello, ${name}.';
+    const inputs: AgentInputs = { name: 'Alice', extra: 'ignored' };
+    const result = templateString(template, inputs);
+    expect(result).toBe('Hello, Alice.');
+  });
+
+  it('should throw an error if a required key is missing from the inputs', () => {
+    const template = 'The goal is ${goal}.';
+    const inputs: AgentInputs = { other_input: 'some value' };
+
+    expect(() => templateString(template, inputs)).toThrow(
+      'Template validation failed: Missing required input parameters: goal. Available inputs: other_input',
+    );
+  });
+
+  it('should throw an error listing all missing keys if multiple are missing', () => {
+    const template = 'Analyze ${file} with ${tool}.';
+    const inputs: AgentInputs = { an_available_key: 'foo' };
+
+    // Using a regex to allow for any order of missing keys in the error message
+    expect(() => templateString(template, inputs)).toThrow(
+      /Missing required input parameters: (file, tool|tool, file)/,
+    );
+  });
+
+  it('should be case-sensitive with placeholder keys', () => {
+    const template = 'Value: ${Key}';
+    const inputs: AgentInputs = { key: 'some value' }; // 'key' is lowercase
+
+    expect(() => templateString(template, inputs)).toThrow(
+      'Template validation failed: Missing required input parameters: Key. Available inputs: key',
+    );
+  });
+
+  it('should not replace malformed or incomplete placeholders', () => {
+    const template =
+      'This is {not_a_placeholder} and this is $$escaped. Test: ${valid}';
+    const inputs: AgentInputs = { valid: 'works' };
+    const result = templateString(template, inputs);
+    expect(result).toBe(
+      'This is {not_a_placeholder} and this is $$escaped. Test: works',
+    );
+  });
+
+  it('should work correctly with an empty inputs object if the template has no placeholders', () => {
+    const template = 'Static text.';
+    const inputs: AgentInputs = {};
+    const result = templateString(template, inputs);
+    expect(result).toBe('Static text.');
+  });
+});