Prompt Engineering with Claude: Getting Reliable JSON Output in TypeScript

import { Anthropic } from '@anthropic-ai/sdk';

// Create a client – the SDK takes your API key from the ANTHROPIC_API_KEY env var
const client = new Anthropic();

// Prompt that simply says “return JSON”
const prompt = `
You are a task‑list generator. Return JSON that looks like:
{
  "tasks": [
    { "title": string, "due": string, "completed": boolean }
  ]
}
`;

// Call the /messages endpoint (simplified)
const response = await client.completions.create({
  model: 'claude-3-5-sonnet-20240620',
  max_tokens: 500,
  messages: [{ role: 'user', content: prompt }],
});

console.log(response.content); // <-- often malformed JSON!

{
  "tasks": [
    { "title": "Buy milk", "due": "2026‑09‑01", "completed": false, }
  ] // note the extra comma
}

// 1️⃣ Define the shape we expect from Claude
type Task = {
  title: string;
  due: string;          // ISO‑8601 date string, e.g. "2026-09-01"
  completed: boolean;
};

type TaskList = {
  tasks: Task[];
};

// 2️⃣ Write a plain‑English description that mirrors the type
const taskListSchema = {
  // The outer object must have a single key called "tasks"
  tasks: [
    {
      // Each item in the array must have these three fields
      title: "string",          // any short text
      due: "ISO‑8601 date",     // e.g. "2026-09-01"
      completed: "boolean",    // true or false
    },
  ],
} satisfies TaskList; // ✅ compile‑time check, no runtime cost

npm install @anthropic-ai/sdk zod

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { Anthropic } from '@anthropic-ai/sdk';
import { z } from 'zod';

// -----------------------------------------------------
// 1️⃣ Type definitions (compile‑time only)
// -----------------------------------------------------
type Task = {
  title: string;
  due: string;          // ISO‑8601 date
  completed: boolean;
};

type TaskList = {
  tasks: Task[];
};

// -----------------------------------------------------
// 2️⃣ Zod schema (runtime validation)
// -----------------------------------------------------
const TaskSchema = z.object({
  title: z.string(),
  due: z.string().refine((s) => !isNaN(Date.parse(s)), {
    message: 'must be a valid ISO‑8601 date',
  }),
  completed: z.boolean(),
});

const TaskListSchema = z.object({
  tasks: z.array(TaskSchema),
});

// -----------------------------------------------------
// 3️⃣ Prompt builder – uses the `satisfies` trick
// -----------------------------------------------------
const taskListSchemaLiteral = {
  tasks: [
    {
      title: 'string',
      due: 'ISO‑8601 date',
      completed: 'boolean',
    },
  ],
} satisfies TaskList; // compile‑time guarantee

function buildPrompt(): string {
  return `
You are a helpful assistant that creates a to‑do list.
Return **only** a JSON object that matches this exact schema:

${JSON.stringify(taskListSchemaLiteral, null, 2)}

The JSON must be the *only* content in your reply. No explanations, no extra fields.
`;
}

// -----------------------------------------------------
// 4️⃣ Helper: call Claude and get raw JSON string
// -----------------------------------------------------
const client = new Anthropic(); // picks up ANTHROPIC_API_KEY automatically

async function callClaude(prompt: string): Promise<string> {
  const response = await client.messages.create({
    model: 'claude-3-5-sonnet-20240620',
    max_tokens: 500,
    temperature: 0, // deterministic output helps with repeatability
    messages: [{ role: 'user', content: prompt }],
  });

  // SDK returns an array of content blocks – join them together
  const raw = response.content
    .map((block) => (typeof block === 'string' ? block : block.text))
    .join('')
    .trim();

  // If Claude added a leading explanation, strip everything before the first '{'
  const jsonStart = raw.indexOf('{');
  return jsonStart >= 0 ? raw.slice(jsonStart) : raw;
}

// -----------------------------------------------------
// 5️⃣ Main Lambda handler
// -----------------------------------------------------
export const handler = async (
  _event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  // First attempt with the normal prompt
  let attempt = 1;
  let jsonString = await callClaude(buildPrompt());

  // -------------------------------------------------
  // 6️⃣ Runtime validation – Zod will throw if mismatch
  // -------------------------------------------------
  try {
    const parsed = TaskListSchema.parse(JSON.parse(jsonString));
    // If we reach here, the data matches the schema
    return {
      statusCode: 200,
      body: JSON.stringify({ message: 'Success', data: parsed }),
    };
  } catch (err) {
    // -------------------------------------------------
    // 7️⃣ Retry with a stricter prompt if first try fails
    // -------------------------------------------------
    if (attempt === 1) {
      attempt++;
      const stricterPrompt = `
${buildPrompt()}

**IMPORTANT**: Do not add any comments, trailing commas, or extra whitespace. 
If you are unsure, return an empty array for "tasks" instead of malformed JSON.
`;
      jsonString = await callClaude(stricterPrompt);
      try {
        const parsed = TaskListSchema.parse(JSON.parse(jsonString));
        return {
          statusCode: 200,
          body: JSON.stringify({ message: 'Success (after retry)', data: parsed }),
        };
      } catch (secondErr) {
        // -------------------------------------------------
        // 8️⃣ Final fallback – manual sanitization
        // -------------------------------------------------
        const cleaned = jsonString
          .replace(/,\s*}/g, '}')          // remove trailing commas before }
          .replace(/,\s*]/g, ']')          // remove trailing commas before ]
          .replace(/\/\/.*$/gm, '')        // strip line‑comments if any
          .trim();

        try {
          const parsed = TaskListSchema.parse(JSON.parse(cleaned));
          return {
            statusCode: 200,
            body: JSON.stringify({
              message: 'Success (after cleanup)',
              data: parsed,
            }),
          };
        } catch (_) {
          // If we still can't parse, return a clear error
          return {
            statusCode: 500,
            body: JSON.stringify({
              error: 'Failed to obtain valid JSON from Claude after two attempts.',
              rawResponse: jsonString,
            }),
          };
        }
      }
    }

    // If we get here (should not happen), report the error
    return {
      statusCode: 500,
      body: JSON.stringify({
        error: 'Validation failed on first attempt.',
        details: (err as Error).message,
      }),
    };
  }
};

const StrictTaskListSchema = TaskListSchema.strict(); // rejects unknown keys

\`\`\`json
{ "tasks": [] }
\`\`\`

jsonString = jsonString.replace(/^```
{% endraw %}
json\s*|
{% raw %}
```$/g, '').trim();