Building Agentic Workflows with Anthropic's Claude: A Production Guide

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

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// Define tools with precise descriptions — Claude is very responsive to description quality
const tools: Anthropic.Tool[] = [
  {
    name: 'generate_fashion_image',
    description: 'Generate an AI fashion image with a specific model, outfit, pose, and background. Use this when the workflow requires a new image to be created. Returns an image URL and generation metadata.',
    input_schema: {
      type: 'object',
      properties: {
        model_id: {
          type: 'string',
          description: 'The AI model ID to use for the fashion shoot',
        },
        outfit_description: {
          type: 'string',
          description: 'Detailed description of the outfit including colors, fabrics, and style',
        },
        pose: {
          type: 'string',
          enum: ['standing', 'walking', 'seated', 'editorial', 'candid'],
          description: 'The pose style for the model',
        },
        background: {
          type: 'string',
          description: 'Background setting description (e.g., "minimalist white studio", "urban street")',
        },
        aspect_ratio: {
          type: 'string',
          enum: ['1:1', '4:5', '9:16', '16:9'],
          description: 'Output image aspect ratio',
        },
      },
      required: ['model_id', 'outfit_description', 'pose'],
    },
  },
  {
    name: 'evaluate_image_quality',
    description: 'Run quality checks on a generated image. Evaluates resolution, composition, brand guideline compliance, and visual artifacts. Returns a score (0-100) and specific feedback.',
    input_schema: {
      type: 'object',
      properties: {
        image_url: { type: 'string', description: 'URL of the image to evaluate' },
        brand_guidelines: { type: 'string', description: 'Brand style guidelines to check against' },
      },
      required: ['image_url'],
    },
  },
  {
    name: 'publish_to_catalog',
    description: 'Publish a finalized image to the product catalog. This is a high-stakes action — only use after quality checks pass. Returns the catalog entry ID.',
    input_schema: {
      type: 'object',
      properties: {
        image_url: { type: 'string' },
        product_id: { type: 'string' },
        metadata: {
          type: 'object',
          properties: {
            title: { type: 'string' },
            tags: { type: 'array', items: { type: 'string' } },
          },
        },
      },
      required: ['image_url', 'product_id'],
    },
  },
];

interface AgentConfig {
  systemPrompt: string;
  tools: Anthropic.Tool[];
  maxTurns: number;
  model: string;
  enableThinking: boolean;
}

async function runClaudeAgent(
  goal: string,
  config: AgentConfig,
  toolExecutors: Map<string, (input: unknown) => Promise<unknown>>
): Promise<AgentResult> {
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: goal },
  ];

  for (let turn = 0; turn < config.maxTurns; turn++) {
    const response = await anthropic.messages.create({
      model: config.model,
      max_tokens: 4096,
      system: config.systemPrompt,
      tools: config.tools,
      messages,
      ...(config.enableThinking && {
        thinking: { type: 'enabled', budget_tokens: 2048 },
      }),
    });

    // Check if Claude wants to use tools
    if (response.stop_reason === 'tool_use') {
      // Add Claude's response (which includes tool_use blocks)
      messages.push({ role: 'assistant', content: response.content });

      // Execute each tool call and collect results
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type === 'tool_use') {
          const executor = toolExecutors.get(block.name);
          if (!executor) {
            toolResults.push({
              type: 'tool_result',
              tool_use_id: block.id,
              content: `Error: Unknown tool "${block.name}"`,
              is_error: true,
            });
            continue;
          }

          try {
            const result = await executor(block.input);
            toolResults.push({
              type: 'tool_result',
              tool_use_id: block.id,
              content: JSON.stringify(result),
            });
          } catch (error) {
            toolResults.push({
              type: 'tool_result',
              tool_use_id: block.id,
              content: `Tool execution failed: ${error.message}`,
              is_error: true,
            });
          }
        }
      }

      messages.push({ role: 'user', content: toolResults });
    } else {
      // Claude returned a final text response — agent is done
      const textContent = response.content
        .filter(b => b.type === 'text')
        .map(b => b.text)
        .join('\n');

      return {
        success: true,
        output: textContent,
        turns: turn + 1,
        thinking: response.content
          .filter(b => b.type === 'thinking')
          .map(b => b.thinking),
      };
    }
  }

  return { success: false, output: 'Max turns reached', turns: config.maxTurns };
}

// Enable extended thinking for complex decisions
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 16000,
  thinking: {
    type: 'enabled',
    budget_tokens: 4096, // Give Claude room to think deeply
  },
  system: `You are a fashion quality control agent. Evaluate images against brand guidelines.
    Think carefully about composition, color accuracy, and model representation before scoring.`,
  tools: qualityCheckTools,
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Evaluate this generated image against our luxury brand guidelines.' },
        { type: 'image', source: { type: 'url', url: imageUrl } },
      ],
    },
  ],
});

// Extract thinking for audit log
const thinkingBlocks = response.content.filter(b => b.type === 'thinking');
await auditLog.save({
  agentAction: 'quality_check',
  reasoning: thinkingBlocks.map(b => b.thinking).join('\n'),
  decision: response.content.filter(b => b.type === 'text'),
  timestamp: new Date(),
});

// Force structured output by defining a "result" tool
const structuredOutputTool: Anthropic.Tool = {
  name: 'submit_evaluation',
  description: 'Submit the final quality evaluation. You MUST call this tool with your evaluation results.',
  input_schema: {
    type: 'object',
    properties: {
      overall_score: { type: 'number', minimum: 0, maximum: 100 },
      composition_score: { type: 'number', minimum: 0, maximum: 100 },
      brand_compliance: { type: 'boolean' },
      issues: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            severity: { type: 'string', enum: ['critical', 'major', 'minor'] },
            description: { type: 'string' },
            suggestion: { type: 'string' },
          },
          required: ['severity', 'description'],
        },
      },
      approved_for_catalog: { type: 'boolean' },
      reasoning: { type: 'string' },
    },
    required: ['overall_score', 'brand_compliance', 'approved_for_catalog', 'reasoning'],
  },
};

const agentSystemPrompt = `You are a fashion workflow automation agent at Modelia.ai.

## Your Role
You orchestrate AI fashion image generation workflows. You plan shoots, generate images,
run quality checks, and iterate until the output meets brand standards.

## Rules
1. ALWAYS run quality checks before publishing to catalog
2. If quality score is below 80, regenerate with adjusted parameters — do NOT publish
3. Maximum 3 regeneration attempts per image. After 3 failures, escalate to human review
4. Use extended thinking to reason through creative decisions
5. When multiple images are needed, generate them in parallel when possible

## Tool Usage Guidelines
- generate_fashion_image: Use for creating new images. Be specific with outfit descriptions.
- evaluate_image_quality: Use AFTER every generation. Never skip quality checks.
- publish_to_catalog: ONLY after quality score >= 80 and brand_compliance is true.
- escalate_to_human: When you've exhausted retries or face ambiguous brand guidelines.

## Output Format
After completing a workflow, summarize: images generated, quality scores, published items,
and any escalations. Be concise.`;

async function callClaudeWithRetry(
  params: Anthropic.MessageCreateParams,
  maxRetries: number = 3
): Promise<Anthropic.Message> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await anthropic.messages.create(params);
    } catch (error) {
      if (error instanceof Anthropic.RateLimitError) {
        const waitMs = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        console.log(`Rate limited. Retrying in ${waitMs}ms (attempt ${attempt + 1})`);
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }

      if (error instanceof Anthropic.APIError && error.status === 529) {
        // Overloaded — back off more aggressively
        const waitMs = Math.pow(2, attempt) * 5000;
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }

      throw error; // Non-retryable error
    }
  }

  throw new Error('Max retries exceeded for Claude API call');
}

interface AgentMetrics {
  workflowId: string;
  model: string;
  totalTurns: number;
  toolCallCount: number;
  toolErrorCount: number;
  thinkingTokensUsed: number;
  totalInputTokens: number;
  totalOutputTokens: number;
  estimatedCost: number;
  qualityScore: number | null;
  escalated: boolean;
  durationMs: number;
}

// Log after every agent run
async function logAgentMetrics(metrics: AgentMetrics) {
  await analytics.track('agent_workflow_complete', metrics);

  // Alert if cost is unexpectedly high
  if (metrics.estimatedCost > COST_THRESHOLD) {
    await alerting.notify(`Agent workflow ${metrics.workflowId} cost ${metrics.estimatedCost.toFixed(2)}`);
  }
}