Skip to content

AI Quick Start

Import pattern

Use your configured Apps Script library identifier (recommended: ASTLib) and normalize once:

const ASTX = ASTLib.AST || ASTLib;

1) Configure script properties

Set provider-native keys in script properties (Project Settings -> Script properties):

  • OPENAI_API_KEY, OPENAI_MODEL
  • GEMINI_API_KEY, GEMINI_MODEL
  • OPENROUTER_API_KEY, OPENROUTER_MODEL
  • PERPLEXITY_API_KEY, PERPLEXITY_MODEL
  • VERTEX_PROJECT_ID, VERTEX_LOCATION, VERTEX_GEMINI_MODEL

Resolution order for auth/model values:

  1. per-call request.auth.* and request.model
  2. runtime config loaded via ASTX.AI.configure(...)
  3. script properties

Optional one-time runtime config load:

const ASTX = ASTLib.AST || ASTLib;
ASTX.AI.configure(PropertiesService.getScriptProperties().getProperties());

For consumer library projects, this configure(...) step is the most reliable way to reuse your own script properties across AI calls.

2) Text generation

function aiTextExample() {
  const response = ASTX.AI.text({
    provider: 'openai',
    input: 'Write a one-line status update.',
    options: {
      maxOutputTokens: 120
    }
  });

  Logger.log(response.output.text);
}

3) Structured output

function aiStructuredExample() {
  const response = ASTX.AI.structured({
    provider: 'gemini',
    input: 'Return a JSON object with priority and owner.',
    schema: {
      type: 'object',
      properties: {
        priority: { type: 'string' },
        owner: { type: 'string' }
      },
      required: ['priority', 'owner'],
      additionalProperties: false
    },
    options: {
      reliability: {
        maxSchemaRetries: 2,
        repairMode: 'json_repair',
        strictValidation: true
      }
    }
  });

  Logger.log(JSON.stringify(response.output.json));
}

4) Tool calling

function aiToolExample() {
  const response = ASTX.AI.tools({
    provider: 'openai',
    input: 'What is 12 + 30?',
    tools: [{
      name: 'add_numbers',
      description: 'Adds two numbers',
      inputSchema: {
        type: 'object',
        properties: {
          a: { type: 'number' },
          b: { type: 'number' }
        },
        required: ['a', 'b']
      },
      handler: args => args.a + args.b
    }],
    options: {
      maxToolRounds: 3
    }
  });

  Logger.log(response.output.text);
  Logger.log(JSON.stringify(response.output.toolResults));
}

5) Image generation

function aiImageExample() {
  const response = ASTX.AI.image({
    provider: 'openai',
    input: 'An icon of a spreadsheet with sparkles',
    model: 'gpt-image-1'
  });

  const image = response.output.images[0];
  const blob = Utilities.newBlob(
    Utilities.base64Decode(image.base64),
    image.mimeType,
    'ai-image.png'
  );

  DriveApp.createFile(blob);
}

Notes

  • Use ASTX.AI.providers() for supported providers.
  • Use ASTX.AI.capabilities(provider) to check provider-level operation support.
  • Structured calls support deterministic reliability controls in options.reliability.
  • Set options.includeRaw=true when you need provider-native raw payloads for debugging.