Claude API Code Execution Integration - Advanced Tools Guide

Claude's code execution runs Python 3.11 in isolated containers that crash when you least expect it. Got about 950MB RAM before it kills your process without warning - learned this trying to load a 180MB CSV that crashed 6 times before I figured out pandas was eating 800MB just parsing it. The environment has the usual data science libraries - pandas 1.5.3, numpy 1.24.3, matplotlib 3.7.1, scikit-learn 1.2.2 - but don't expect bleeding edge versions, they're like 8 months behind.

Container Environment Limits

Python 3.11.7 running on Ubuntu Linux, locked down tight with no internet access. Can't pip install anything, what's included is what you get. Found out the hard way when I tried to use pandas.DataFrame.map() (added in 2.1.0) with their 1.5.3 version and got AttributeError for three fucking hours thinking I was going crazy.

What you're actually working with:

• Memory: 950MB before OOMKilled with zero warning
• Storage: 2GB temp space until you load a real dataset
• Libraries: Standard data science stack, 6-8 months behind latest
• Internet: Completely blocked for security (can't even ping 8.8.8.8)
• Container cost: $0.05/hour until you forget cleanup and hit $1200/month
• Lifetime: Max 1 hour, often dies after 45 minutes for no reason

How This Actually Works with Express

Your Express app turns into a container babysitter - managing async operations that hang forever, containers that die mid-execution, and error messages that tell you absolutely nothing useful. Simple text completion responds in 2-3 seconds, but code execution takes 30-90 seconds and fails in ways you never imagined possible.

What You Actually Need:

{
  \"dependencies\": {
    \"@anthropic-ai/sdk\": \"^0.28.0\", // They fix critical bugs weekly, stay current
    \"express\": \"^4.19.2\", // Any recent version works fine
    \"multer\": \"^1.4.5\", // For file uploads that will definitely break everything
    \"helmet\": \"^7.1.0\" // Basic security, containers will still bankrupt you
  }
}

The Simplest Setup That Actually Works

This handles basic Python execution. Works great for math and small datasets. Breaks horribly when you try anything complex.

What You'll Actually Build:

// services/codeExecutionService.ts
import Anthropic from '@anthropic-ai/sdk';

export class CodeExecutionService {
  private client: Anthropic;

  constructor(apiKey: string) {
    this.client = new Anthropic({
      apiKey,
      defaultHeaders: {
        'anthropic-beta': 'code-execution-2024-10-22' // This beta header breaks if you use wrong date
      }
    });
  }

  // TODO: this error handling is terrible but it works
  async executeAnalysis(prompt: string, containerId?: string) {
    try {
      // Cross your fingers the container doesn't randomly die mid-execution
      const response = await this.client.messages.create({
        model: 'claude-3-5-sonnet-20241022', // Current Sonnet, Opus costs 3x more for same shit
        max_tokens: 4096, // Max you can actually use, will need all of it for real output
        container: containerId, // Reuse containers or pay $0.05/hour for each new one
        messages: [{ role: 'user', content: prompt }],
        tools: [{
          type: 'code_execution_20241022',
          name: 'code_execution'
        }]
      });

      return {
        content: response.content,
        containerId: response.container?.id, // Save this or lose all your fucking data
        expiresAt: response.container?.expires_at // Usually 1 hour, sometimes 47 minutes
      };
    } catch (error) {
      // Error messages are cryptic as hell, good luck debugging this shit
      console.error('Container execution failed:', error);
      throw new Error(`Execution failed: ${error.message || 'Container died for mysterious reasons'}`);
    }
  }
}

The Express Route (With Realistic Timeouts):

// routes/analysis.ts
import { Router } from 'express';
import { CodeExecutionService } from '../services/codeExecutionService';

const router = Router();
const codeExecution = new CodeExecutionService(process.env.ANTHROPIC_API_KEY!);

router.post('/analyze', async (req, res) => {
  const { prompt, containerId } = req.body;
  
  // Set a realistic timeout - containers hang for 3+ minutes when they feel like it
  req.setTimeout(180000); // 3 minutes max, learned this after 100+ timeouts
  
  try {
    const result = await codeExecution.executeAnalysis(prompt, containerId);
    
    res.json({
      success: true,
      result: result.content,
      container: {
        id: result.containerId, // Store this for subsequent requests or you start over
        expiresAt: result.expiresAt // Usually in ~57 minutes, not the full hour
      }
    });
  } catch (error) {
    // Log absolutely everything for debugging - you'll need every bit of context
    console.error('Analysis failed:', error);
    res.status(500).json({
      error: 'Container execution failed',
      message: error.message || 'Container died for no goddamn reason'
    });
  }
});

export { router as analysisRoutes };

File Processing (Where Things Get Expensive)

File uploads plus code execution - works fine for 5MB test files, crashes spectacularly on anything real. First week in production some fucking user uploaded a 284MB Excel file with 900,000 rows and killed every single container we had running. Took 6 hours to figure out containers were hanging around because cleanup wasn't working right - had 47 dead containers burning through cash. March bill was $1,847.32 instead of the expected $200. Check out Multer documentation for file handling and Node.js streams for large file processing. The Files API limits are real and will bite you in the ass.

File Processing Service:

// services/fileProcessingService.ts
import multer from 'multer';
import { Readable } from 'stream';

export class FileProcessingService extends CodeExecutionService {
  private upload = multer({ 
    storage: multer.memoryStorage(),
    limits: { fileSize: 25 * 1024 * 1024 } // 25MB limit learned after pandas crashed trying to load 50MB
  });

  async uploadAndAnalyze(file: Express.Multer.File, analysisPrompt: string) {
    // Upload file to Claude Files API
    const uploadedFile = await this.client.files.create({
      file: new Readable({
        read() {
          this.push(file.buffer);
          this.push(null);
        }
      }),
      purpose: 'user_data'
    });

    // Process with code execution (pray it doesn't crash)
    const response = await this.client.messages.create({
      model: 'claude-3-5-sonnet-20241022', // Opus is 3x more expensive and not worth it
      max_tokens: 8192,
      messages: [{
        role: 'user',
        content: [
          { type: 'text', text: analysisPrompt },
          { type: 'container_upload', file_id: uploadedFile.id }
        ]
      }],
      tools: [{
        type: 'code_execution_20241022',
        name: 'code_execution'
      }]
    });

    return response;
  }
}

Container Management for Stateful Workflows

Container reuse enables sophisticated workflows where previous calculations, loaded datasets, or generated files persist across requests. This is essential for iterative data analysis, multi-step processing pipelines, or maintaining user-specific work environments.

Container Lifecycle Management:

// services/containerManager.ts
export class ContainerManager {
  private containers = new Map<string, ContainerInfo>();

  async createWorkspace(userId: string): Promise<string> {
    const containerId = await this.initializeContainer();
    
    this.containers.set(userId, {
      containerId,
      createdAt: new Date(),
      lastUsed: new Date(),
      expiresAt: new Date(Date.now() + 60 * 60 * 1000) // 1 hour
    });

    return containerId;
  }

  async getWorkspace(userId: string): Promise<string | null> {
    const container = this.containers.get(userId);
    
    if (!container || container.expiresAt < new Date()) {
      this.containers.delete(userId);
      return null;
    }

    container.lastUsed = new Date();
    return container.containerId;
  }

  async executeInWorkspace(userId: string, prompt: string) {
    let containerId = await this.getWorkspace(userId);
    
    if (!containerId) {
      containerId = await this.createWorkspace(userId);
    }

    return this.codeExecution.executeAnalysis(prompt, containerId);
  }
}

Advanced Error Handling Patterns

Code execution introduces unique failure modes: Python syntax errors, runtime exceptions, resource limits, container expiration, and network timeouts. Robust error handling distinguishes professional applications from fragile prototypes.

Comprehensive Error Handler:

// middleware/codeExecutionErrorHandler.ts
export class CodeExecutionErrorHandler {
  static handle(error: any, req: Request, res: Response, next: NextFunction) {
    if (error.type === 'code_execution_tool_result_error') {
      switch (error.error_code) {
        case 'unavailable':
          return res.status(503).json({
            error: 'Code execution service unavailable',
            message: 'The analysis service is temporarily unavailable. Please try again.',
            retryAfter: '5 minutes'
          });
        
        case 'code_execution_exceeded':
          return res.status(408).json({
            error: 'Execution timeout',
            message: 'Code execution exceeded maximum allowed time. Simplify your analysis.',
            maxExecutionTime: '60 seconds'
          });
          
        case 'container_expired':
          return res.status(409).json({
            error: 'Session expired',
            message: 'Your analysis session expired. Start a new session.',
            action: 'create_new_session'
          });
      }
    }

    // Handle Python runtime errors
    if (error.content?.stderr) {
      const pythonError = this.parsePythonError(error.content.stderr);
      return res.status(400).json({
        error: 'Python execution error',
        message: 'Code execution failed with error',
        details: pythonError
      });
    }

    next(error);
  }
}

Production Monitoring and Observability

Code execution requires specialized monitoring beyond traditional API metrics. Track execution times, container usage, error patterns, and resource consumption to maintain reliable service performance.

Monitoring Implementation:

// middleware/executionMetrics.ts
export class ExecutionMetrics {
  static trackExecution = (req: Request, res: Response, next: NextFunction) => {
    const startTime = Date.now();
    
    res.on('finish', () => {
      const duration = Date.now() - startTime;
      const containerId = res.locals.containerId;
      
      // Track metrics
      metrics.executionDuration.record(duration, {
        userId: req.user?.id,
        containerId,
        success: res.statusCode < 400
      });
      
      metrics.containerUsage.increment({
        action: containerId ? 'reused' : 'created'
      });
    });
    
    next();
  };
}

Code execution turns your Express app into something actually useful instead of another boring CRUD API that pushes JSON around. Users upload datasets, ask for analysis, and get back visualizations and insights that would take weeks to build yourself. The architecture patterns for this are way more complex than simple CRUD bullshit.

Now you can build automated reporting, data pipelines, document processing, and interactive analysis tools. Way better than writing custom data processing from scratch and debugging fucking pandas memory errors for days.

Multi-tool workflows sound awesome until you're debugging why file uploads work perfectly but Python execution hangs forever on line 47 of a pandas operation. Managing file uploads, code execution, image processing, and data transforms simultaneously - each one fails in completely different ways with zero useful error messages. Spent two entire days figuring out which fucking tool died when everything just stopped responding at 3AM during a demo.

How Multi-Tool Workflows Actually Work

Request flow becomes: upload file → parse with Python → generate charts → format results → pray nothing times out in the middle. Claude decides which tools to use (sometimes wrong), but you're babysitting async operations that fail randomly at any step for no reason. Spent 4 hours debugging with network inspector trying to find which tool silently died. Log absolutely fucking everything or you'll lose your mind trying to trace failures.

Tool Orchestration Service:

// services/toolOrchestrator.ts
export class ToolOrchestrator {
  private client: Anthropic;
  private fileService: FileService;
  private containerManager: ContainerManager;

  async processComplexRequest(request: ComplexAnalysisRequest): Promise<ProcessingResult> {
    const workflow = new WorkflowBuilder()
      .addStep('file_validation', () => this.validateInputFiles(request.files))
      .addStep('file_upload', () => this.uploadFiles(request.files))
      .addStep('analysis_execution', () => this.executeAnalysis(request.prompt))
      .addStep('result_processing', () => this.processResults())
      .build();

    return await workflow.execute();
  }

  private async executeAnalysis(prompt: string, files?: UploadedFile[]): Promise<AnalysisResult> {
    const tools = [
      { type: 'code_execution_20250522', name: 'code_execution' }
    ];

    // Add files to message context if provided
    const messageContent = [
      { type: 'text', text: prompt }
    ];

    if (files) {
      files.forEach(file => {
        messageContent.push({
          type: 'container_upload',
          file_id: file.anthropicFileId
        });
      });
    }

    const response = await this.client.messages.create({
      model: 'claude-3-5-sonnet-20241022', // Opus costs 3x more and isn't worth it for most workflows
      max_tokens: 8192,
      messages: [{ role: 'user', content: messageContent }],
      tools,
      tool_choice: { type: 'auto' } // Let Claude choose tools (and pray it picks right)
    });

    return this.parseAnalysisResponse(response);
  }
}

Advanced File Processing Pipelines

Real apps handle diverse file types, sizes, and processing requirements without falling over. A solid file processing pipeline includes validation, format conversion, preprocessing, analysis, and cleanup - all while maintaining security, performance, and not pissing off users when their 200MB Excel file crashes your entire system.

File Processing Pipeline:

// services/fileProcessingPipeline.ts
export class FileProcessingPipeline {
  private readonly MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB - learned after crashes above this
  private readonly SUPPORTED_FORMATS = ['.csv', '.xlsx', '.json', '.txt', '.png', '.jpg']; // Users will try .exe files

  async processBatch(files: Express.Multer.File[], analysisType: string): Promise<BatchResult> {
    // Stage 1: Validation and preprocessing
    const validatedFiles = await this.validateAndPreprocess(files);
    
    // Stage 2: Upload to Anthropic Files API
    const uploadedFiles = await Promise.all(
      validatedFiles.map(file => this.uploadToAnthropic(file))
    );

    // Stage 3: Execute analysis with proper tool selection
    const analysisResults = await this.executeAnalysisWorkflow(uploadedFiles, analysisType);

    // Stage 4: Post-processing and cleanup
    await this.cleanupTempFiles(uploadedFiles);
    
    return {
      results: analysisResults,
      processedFiles: uploadedFiles.length,
      totalSize: validatedFiles.reduce((sum, f) => sum + f.size, 0)
    };
  }

  private async validateAndPreprocess(files: Express.Multer.File[]): Promise<PreprocessedFile[]> {
    return Promise.all(files.map(async (file) => {
      // Size validation
      if (file.size > this.MAX_FILE_SIZE) {
        throw new ValidationError(`File ${file.originalname} exceeds size limit`);
      }

      // Format validation
      const ext = path.extname(file.originalname).toLowerCase();
      if (!this.SUPPORTED_FORMATS.includes(ext)) {
        throw new ValidationError(`Unsupported file format: ${ext}`);
      }

      // Content validation for CSV files
      if (ext === '.csv') {
        return this.preprocessCSV(file);
      }

      // Image preprocessing
      if (['.png', '.jpg', '.jpeg'].includes(ext)) {
        return this.preprocessImage(file);
      }

      return { ...file, preprocessed: true };
    }));
  }

  private async preprocessCSV(file: Express.Multer.File): Promise<PreprocessedFile> {
    const csvString = file.buffer.toString('utf-8');
    
    // Basic CSV validation
    const lines = csvString.split('
');
    if (lines.length < 2) {
      throw new ValidationError('CSV must have at least header and one data row');
    }

    // Detect and handle encoding issues
    const cleanedCSV = this.cleanCSVContent(csvString);
    
    return {
      ...file,
      buffer: Buffer.from(cleanedCSV, 'utf-8'),
      preprocessed: true,
      metadata: {
        rows: lines.length - 1,
        columns: lines[0].split(',').length
      }
    };
  }
}

Streaming with Tool Orchestration

Streaming responses become complex when tools are involved. Code execution might take 30+ seconds, file processing adds latency, and users need real-time feedback. Implement streaming patterns that provide meaningful progress updates without overwhelming the client.

Advanced Streaming Implementation:

// services/streamingOrchestrator.ts
export class StreamingOrchestrator {
  async streamComplexAnalysis(req: Request, res: Response) {
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    const sendEvent = (event: string, data: any) => {
      res.write(`event: ${event}
data: ${JSON.stringify(data)}

`);
    };

    try {
      sendEvent('status', { stage: 'initializing', message: 'Starting analysis...' });

      // Stream the Claude response with tool orchestration
      const stream = await this.client.messages.create({
        model: 'claude-3-opus-20240229',
        max_tokens: 8192,
        messages: [{ role: 'user', content: req.body.prompt }],
        tools: [{ type: 'code_execution_20250522', name: 'code_execution' }],
        stream: true
      });

      let currentStage = 'reasoning';
      
      for await (const chunk of stream) {
        if (req.destroyed) break; // Client disconnected

        switch (chunk.type) {
          case 'content_block_start':
            if (chunk.content_block.type === 'server_tool_use') {
              currentStage = 'executing';
              sendEvent('status', { 
                stage: currentStage, 
                message: 'Executing Python code...',
                tool: chunk.content_block.name 
              });
            }
            break;

          case 'content_block_delta':
            if (chunk.delta.type === 'text_delta') {
              sendEvent('content', { text: chunk.delta.text });
            }
            break;

          case 'code_execution_tool_result':
            sendEvent('execution_result', {
              stdout: chunk.content.stdout,
              stderr: chunk.content.stderr,
              return_code: chunk.content.return_code
            });
            break;

          case 'message_stop':
            sendEvent('complete', { stage: 'finished' });
            break;
        }
      }

    } catch (error) {
      sendEvent('error', { 
        message: error.message,
        stage: currentStage 
      });
    } finally {
      res.end();
    }
  }
}

Production-Grade Error Recovery

This will break. When it does, you'll have partial uploads, dead containers, cascading timeouts, and no idea what state everything's in. Need error recovery that actually works and gives users something more helpful than "something went wrong."

Error Recovery System:

// services/errorRecoveryService.ts
export class ErrorRecoveryService {
  private retryPolicies: Map<string, RetryPolicy> = new Map([
    ['container_expired', { maxRetries: 2, backoffMs: 1000, strategy: 'create_new' }],
    ['rate_limit_exceeded', { maxRetries: 5, backoffMs: 60000, strategy: 'exponential_backoff' }],
    ['code_execution_exceeded', { maxRetries: 1, backoffMs: 5000, strategy: 'reduce_complexity' }]
  ]);

  async executeWithRecovery<T>(
    operation: () => Promise<T>,
    context: OperationContext
  ): Promise<T> {
    let lastError: Error;
    let attempt = 0;

    while (attempt <= this.getMaxRetries(context.errorType)) {
      try {
        if (attempt > 0) {
          await this.applyRecoveryStrategy(context, attempt);
        }
        
        return await operation();
      } catch (error) {
        lastError = error;
        attempt++;
        
        if (!this.isRetryableError(error)) {
          throw error;
        }
        
        await this.logRetryAttempt(context, error, attempt);
      }
    }

    throw new MaxRetriesExceededError(lastError, attempt);
  }

  private async applyRecoveryStrategy(context: OperationContext, attempt: number) {
    const policy = this.retryPolicies.get(context.errorType);
    
    switch (policy?.strategy) {
      case 'create_new':
        context.containerId = null; // Force new container creation
        break;
        
      case 'exponential_backoff':
        const backoff = policy.backoffMs * Math.pow(2, attempt - 1);
        await this.delay(Math.min(backoff, 300000)); // Max 5 minutes
        break;
        
      case 'reduce_complexity':
        context.maxTokens = Math.floor(context.maxTokens * 0.8);
        context.timeout = Math.floor(context.timeout * 1.2);
        break;
    }
  }
}

Advanced Caching and Performance Optimization

High-performance applications require intelligent caching across multiple layers: response caching, container reuse, file preprocessing results, and computed analysis patterns. Implement caching strategies that balance performance gains with data freshness requirements.

Multi-Layer Caching System:

// services/cachingService.ts
export class AdvancedCachingService {
  private responseCache: LRUCache<string, CachedResponse>;
  private containerCache: Map<string, ContainerSession>;
  private fileCache: Redis;

  async getCachedAnalysis(request: AnalysisRequest): Promise<CachedResponse | null> {
    const cacheKey = this.generateCacheKey(request);
    
    // Layer 1: Memory cache for frequent requests
    const memoryResult = this.responseCache.get(cacheKey);
    if (memoryResult && !this.isExpired(memoryResult)) {
      return memoryResult;
    }

    // Layer 2: Redis cache for distributed caching
    const redisResult = await this.fileCache.get(cacheKey);
    if (redisResult) {
      const parsed = JSON.parse(redisResult);
      this.responseCache.set(cacheKey, parsed); // Promote to memory
      return parsed;
    }

    return null;
  }

  async cacheAnalysisResult(request: AnalysisRequest, result: AnalysisResult) {
    const cacheKey = this.generateCacheKey(request);
    const cached: CachedResponse = {
      result,
      timestamp: Date.now(),
      ttl: this.calculateTTL(request),
      metadata: {
        executionTime: result.executionTime,
        containerId: result.containerId,
        toolsUsed: result.toolsUsed
      }
    };

    // Store in both layers
    this.responseCache.set(cacheKey, cached);
    await this.fileCache.setex(
      cacheKey, 
      cached.ttl, 
      JSON.stringify(cached)
    );
  }

  private generateCacheKey(request: AnalysisRequest): string {
    const components = [
      request.prompt,
      request.files?.map(f => f.hash).sort().join(',') || 'no-files',
      request.model || 'default'
    ];
    
    return crypto
      .createHash('sha256')
      .update(components.join(':'))
      .digest('hex');
  }
}

Deployment and Scaling Considerations

Production deployment of advanced Claude integrations requires careful consideration of resource management, scaling patterns, monitoring, and security. Container management, file storage, caching layers, and error handling all impact deployment architecture.

Production Configuration:

// config/production.ts
export const productionConfig = {
  claude: {
    apiKey: process.env.ANTHROPIC_API_KEY,
    maxConcurrentRequests: 10,
    defaultTimeout: 120000,
    retryAttempts: 3
  },
  containers: {
    maxConcurrentContainers: 5,
    containerTimeout: 3600000, // 1 hour
    cleanupInterval: 300000 // 5 minutes
  },
  files: {
    maxFileSize: 100 * 1024 * 1024, // 100MB
    allowedTypes: ['.csv', '.xlsx', '.json', '.png', '.jpg'],
    storageProvider: 'aws-s3',
    tempDirectory: '/tmp/claude-uploads'
  },
  caching: {
    redis: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT || '6379'),
      ttl: 1800 // 30 minutes default
    },
    memory: {
      maxSize: 100, // 100 cached responses
      ttl: 300 // 5 minutes
    }
  }
};

Multi-tool orchestration sounds impressive until you're dealing with production failures, container cleanup, and error propagation across multiple async operations. Claude's tool selection is black box magic - sometimes it picks the wrong tool and you're screwed. With proper workflow management, caching strategies, and monitoring, you can build something that actually works in production.

The patterns here enable automated reporting, interactive data analysis, document processing, and workflow automation - assuming your containers don't randomly die and take your state with them.