AI Step

Generate AI text or structured data without interactive tool use. Faster and simpler than agent steps.

Overview

The AI step calls AI models directly for text or structured generation. Unlike agent steps, AI steps don't support file editing or tool use.

Use when:

Need quick AI response (< 5 min)
Want structured data with schema validation
Don't need file editing
Single-shot generation (not interactive)

Don't use when:

Need file editing → Use agent step
Need tool use → Use agent step
Task requires >5 minutes → Use agent step

prompt (required) - Your instruction/question provider (optional) - "anthropic" (default) or "openai" model (optional) - Model name (defaults: claude-sonnet-4-5-20250929, gpt-4) systemPrompt (optional) - System instructions temperature (optional) - 0-2, creativity level (default: 0.7) maxTokens (optional) - Max response length schema (optional) - Zod schema for structured output

Basic Usage

Simple Text Generation

const result = await step.ai("generate-docs", {
  prompt: "Write documentation for this authentication module",
  provider: "anthropic",
});

console.log(result.data.text);

Structured Output with Schema

import { z } from "zod";

const schema = z.object({
  complexity: z.number().min(1).max(10),
  issues: z.array(z.object({
    severity: z.enum(["high", "medium", "low"]),
    description: z.string(),
  })),
  recommendations: z.array(z.string()),
});

const result = await step.ai("analyze-code", {
  prompt: "Analyze this codebase for issues",
  schema,
});

// result.data is fully typed!
console.log(result.data.complexity);      // number
console.log(result.data.issues[0].severity); // "high" | "medium" | "low"

With System Prompt

await step.ai("generate-tests", {
  prompt: "Generate unit tests for the auth service",
  systemPrompt: "You are an expert test engineer. Write comprehensive tests with edge cases.",
  temperature: 0.3, // More focused
});

Return Value

interface AiStepResult<T> {
  data: T;              // Structured data (if schema) or { text: string }
  provider: string;
  model: string;
}

Common Patterns

Code Analysis

const analysis = await step.ai("security-scan", {
  prompt: `Analyze this code for security vulnerabilities:
${code}`,
  schema: z.object({
    vulnerabilities: z.array(z.object({
      type: z.string(),
      severity: z.enum(["critical", "high", "medium", "low"]),
      line: z.number(),
      fix: z.string(),
    })),
  }),
});

Data Extraction

const extracted = await step.ai("extract-info", {
  prompt: `Extract key information from this document:
${document}`,
  schema: z.object({
    title: z.string(),
    author: z.string(),
    date: z.string(),
    tags: z.array(z.string()),
  }),
});

Content Generation

await step.ai("write-release-notes", {
  prompt: `Write release notes for version 2.0 based on these commits:
${commits}`,
  temperature: 0.8, // More creative
  maxTokens: 2000,
});

Best Practices

Use schemas for structured data:

// ✅ Good - typed output
schema: z.object({ score: z.number(), issues: z.array(...) })

// ❌ Bad - parse JSON manually
prompt: "Return JSON with score and issues"

Set appropriate temperature:

0-0.3: Factual, focused (analysis, extraction)
0.5-0.7: Balanced (general tasks)
0.8-1.5: Creative (writing, brainstorming)

Keep prompts focused:

// ✅ Good - specific task
prompt: "Extract user ID and email from this API response"

// ❌ Bad - multiple tasks
prompt: "Extract data, analyze it, generate report, and suggest improvements"

AI Step

Overview

Configuration

Parameters