Claude Sonnet 4: A Hands-On Guide for Developers

With the release of Claude Sonnet 4, developers now have access to powerful new capabilities—including native code execution, a flexible Files API, and dynamic tool use. These features open up exciting possibilities for building AI-powered applications that go beyond simple text interactions.

In this tutorial, I’ll walk you through these new features by building a Python-based agent that can solve advanced math problems right from your terminal. You’ll learn to use the newly introduced native code execution tool and the files API.

By the end, you’ll have a working agent powered by Claude Sonnet 4 to analyze problems, write and run Python code, and render visuals like the ones below.

Check out the GitHub repository for this project to see all the code for building the application.

If you're just beginning your journey into building with LLMs like Claude, this AI developer roadmap outlines essential tools, skills, and learning paths to get started.

What’s New in the Anthropic API

Before we go into the tutorial, let’s look at all the recently released new features available through the Anthropic API. Feel free to skip ahead if you’re already aware of them.

I think the entire Claude 4 announcement can be summarized in this one image:

Claude 4 models (Opus and Sonnet 4) beat the competition in verified software engineering tasks by a significant margin. Anthropic achieved this feat by introducing a few important changes to how the models behave:

1. Long runtimes: Both models support several hours of continuous task execution to solve problems with thousands of steps.
2. Extended thinking with tool use: Both models can now use tools like web search during extended thinking, allowing Claude to alternate between reasoning and tool use to improve responses.
3. Parallel tool execution: The models can now use multiple tools simultaneously rather than sequentially.
4. More precise instruction following: Enhanced steerability gives users greater control over implementations and how Claude responds to instructions.
5. Improved memory capabilities: When given access to local files, the models can extract and save key facts to maintain continuity and build tacit knowledge over time.
6. Reduced shortcut behavior: Compared to previous versions, both models are 65% less likely to use shortcuts or loopholes to complete tasks (see the full announcement post for more details).

Additionally, as part of the Claude 4 model family announcement, Anthropic has added four new features for building AI agents: the code execution tool, Files API, MCP connector, and extended prompt caching. These tools change how developers can build AI applications.

Code execution tool: Run Python code securely

The code execution tool allows Claude to run Python code in a secure sandbox environment. Instead of just writing code suggestions, Claude can now execute code, analyze results, and iterate on solutions.

To use the code execution tool, add it to your tools array and include the required beta header:

from anthropic import Anthropic

# Initialize client with the code execution beta header
client = Anthropic(
   default_headers={
       "anthropic-beta": "code-execution-2025-05-22"
   }
)

# Send a request that triggers code execution
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": "Solve the quadratic equation 2x² + 5x - 3 = 0 and plot the parabola"
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

When Claude executes code, the response contains both the generated code and its execution results. Here’s how to parse the different components:

# Parse the response to extract code and results
for item in response.content:
   if item.type == "server_tool_use":
       # This contains the actual Python code Claude wrote
       print(f"Code executed:\n{item.input['code']}")
   elif item.type == "code_execution_tool_result":
       # This contains the output from running the code
       print(f"Output:\n{item.content['stdout']}")
       if item.content.get('stderr'):
           print(f"Errors:\n{item.content['stderr']}")

Sandbox limitations: The code execution environment has several built-in security restrictions. Claude runs in an isolated container with no internet access, limited computational resources (1 GB RAM, 5 GB disk space, and 1 CPU), and cannot access your local file system. The environment comes pre-installed with popular libraries like numpy, pandas, matplotlib, and scipy, but you cannot install additional packages during execution.

Files API: Persistent file context for complex tasks

The Files API allows you to upload documents once and reference them across multiple conversations. This removes the need to include large documents in every API request.

First, upload your file to Anthropic’s servers:

# Upload a file once - this stores it on Anthropic's servers
uploaded_file = client.beta.files.upload(
   file=open("sales_data.csv", "rb"),
   purpose="user_upload"
)
# The uploaded_file.id can now be referenced in multiple conversations

Once uploaded, reference the file in your API calls using the container_upload content type:

# Reference the uploaded file in a conversation
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": [
           {"type": "text", "text": "Create a quarterly sales report from this data"},
           {"type": "container_upload", "file_id": uploaded_file.id}
       ]
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

When Claude creates files during code execution (like plots or processed data), you can extract and download them:

# Extract file IDs of any files Claude created during execution
def extract_created_files(response):
   file_ids = []
   for item in response.content:
       if item.type == 'code_execution_tool_result':
           content = item.content
           if content.get('type') == 'code_execution_result':
               # Look for file objects in the execution results
               for file_obj in content.get('content', []):
                   if 'file_id' in file_obj:
                       file_ids.append(file_obj['file_id'])
   return file_ids

# Download any files Claude created
created_files = extract_created_files(response)
for file_id in created_files:
   file_content = client.beta.files.download(file_id)
   file_content.write_to_file(f"output_{file_id}.png")

MCP connector: Plug Claude into any workflow

The MCP connector brings Model Context Protocol support directly to the API. MCPs allow Claude to connect to external services like databases, APIs, and productivity tools without custom integration code.

Previously, connecting to MCP servers required building client infrastructure. Now, you can simply provide a remote MCP server URL in your API request, and Claude automatically discovers available tools, manages connections, and handles authentication.

This opens up access to a growing ecosystem of MCP servers from companies like Zapier and Asana, allowing you to build agents that can read your calendar, update project management tools, or integrate with hundreds of other services.

Getting Started with Claude Sonnet 4: Project Overview and Setup

Now that we understand the new API features, let’s build our interactive math problem solver. It will combine Claude’s code execution capabilities with file handling to create a complete mathematical assistant.

Our application will accept natural language math questions, execute Python code to solve them, generate visualizations, and save comprehensive reports.

For a structured approach to building projects like this, check out the Developing AI Applications track.

> Note: Since we will be breaking up long code blocks with explanations, the code indentation may not be entirely accurate in snippets. For this reason, we recommend opening the GitHub repo for this project in a separate tab while following along.

Step 0: Set up your Claude Sonnet 4 project environment

Before writing any code, let’s set up our development environment and dependencies.

Create a new directory for your project and set up the required files:

mkdir math-solver
cd math-solver
touch math_solver.py demo_problems.py requirements.txt README.md

Create a requirements.txt file with the necessary dependencies:

anthropic>=0.42.0

Install the dependencies:

pip install -r requirements.txt

Set your Anthropic API key as an environment variable:

export ANTHROPIC_API_KEY="your-api-key-here"

Step 1: Design the application structure

Let’s start by creating the basic structure of our MathSolver class. This class will handle all the main functionality: API communication, file management, and user interaction.

First, let’s set up the imports and basic structure:

#!/usr/bin/env python3
"""
Interactive Math Problem Solver using Claude 4 Code Execution Tool

This application allows users to ask math questions in natural language,
gets solutions using Claude's code execution capabilities, and saves
both visualizations and detailed markdown reports.
"""

import os
import json
import datetime
from pathlib import Path
from typing import List, Dict, Any
from anthropic import Anthropic

Now let’s define our main class structure:

class MathSolver:
   def __init__(self, api_key: str = None):
       """Initialize the Math Solver with Anthropic client."""
       # API setup and directory creation will go here
       pass

   def solve_problem(self, question: str) -> Dict[str, Any]:
       """Send a math question to Claude and get solution with code execution."""
       pass
Here are the methods for file and report handling:
def extract_files_from_response(self, response) -> List[str]:
       """Extract file IDs from Claude's response."""
       pass

   def download_files(self, file_ids: List[str]) -> List[str]:
       """Download files created by code execution to local storage."""
       pass

   def extract_code_blocks(self, response) -> List[str]:
       """Extract all code blocks from the response."""
       Pass

Finally, we add the session management and entry point:

def generate_markdown_report(self, result: Dict[str, Any], downloaded_files: List[str]) -> str:
       """Generate a comprehensive markdown report of the solution."""
       pass

   def run_interactive_session(self):
       """Run the main interactive session loop."""
       pass


def main():
   """Main entry point for the application."""
   pass

This structure gives us a clear roadmap: initialization, problem solving, file handling, report generation, and user interaction. Each method has a specific responsibility in our math-solving pipeline.

Building a Math Solver with Claude Sonnet 4 Code Execution

Now, let’s implement core functionality using Claude's code execution tool and streaming responses.

Step 2: Initialize Claude with secure API headers

Let’s implement the __init__() method to handle API client setup and directory creation.

First, we handle API key management:

def __init__(self, api_key: str = None):
   """Initialize the Math Solver with Anthropic client."""
   if not api_key:
       api_key = os.getenv("ANTHROPIC_API_KEY")
       if not api_key:
           raise ValueError(
               "Please set ANTHROPIC_API_KEY environment variable or provide api_key"
           )

Next, we set up the Anthropic client with the required beta headers:

# Initialize client with both code execution and files API headers
   self.client = Anthropic(
       api_key=api_key,
       default_headers={
           "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
       },
   )

Finally, we create the output directory structure:

# Create organized output directories
   self.output_dir = Path("math_solver_output")
   self.images_dir = self.output_dir / "images"
   self.reports_dir = self.output_dir / "reports"

   self.output_dir.mkdir(exist_ok=True)
   self.images_dir.mkdir(exist_ok=True)
   self.reports_dir.mkdir(exist_ok=True)

   print(f"📁 Output directories created:")
   print(f"   • Images: {self.images_dir}")
   print(f"   • Reports: {self.reports_dir}")

This initialization does three important things:

1. API key management: Checks for the key in environment variables first, then falls back to a parameter.
2. Client setup: Creates an Anthropic client with both beta headers for code execution and files API.
3. Directory structure: Creates organized folders for storing images and reports.

Step 3: Write the core solver function

The solve_problem() method is the heart of our application. It sends requests to Claude with streaming support.

Let’s start with the function signature and initial setup:

def solve_problem(self, question: str) -> Dict[str, Any]:
   """
   Send a math question to Claude and get solution with code execution.
   """
   print(f"\n🤔 Thinking about: {question}")

   try:
       # Use streaming to show real-time progress
       with self.client.messages.stream(
           model="claude-sonnet-4-20250514",
           max_tokens=4096,
Now we configure the message and tool specification:
messages=[
               {
                   "role": "user",
                   "content": f"""Solve this math problem using code execution:

Problem: {question}

Please:
1. Solve the problem with actual Python code
2. Create visualizations using matplotlib if helpful
3. Save any plots as PNG files using plt.savefig()
4. Show your calculations step by step
5. Use descriptive filenames for saved plots

Execute Python code to solve this problem.""",
               }
           ],
           tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
       ) as stream:
The streaming event processing handles real-time updates:
print("\n💭 Claude is working...")

           # Process streaming events and show progress
           for event in stream:
               if event.type == "content_block_start":
                   if hasattr(event.content_block, "type"):
                       if event.content_block.type == "text":
                           print("\n📝 Response:", end=" ", flush=True)
                       elif event.content_block.type == "server_tool_use":
                           print(f"\n🔧 Using tool: {event.content_block.name}")

We handle different types of streaming events:

	elif event.type == "content_block_delta":
                   if hasattr(event.delta, "text"):
                       print(event.delta.text, end="", flush=True)

               elif event.type == "content_block_stop":
                   print("", flush=True)  # New line

               elif event.type == "message_delta":
                   if hasattr(event.delta, "stop_reason"):
                       print(f"\n✅ Completed: {event.delta.stop_reason}")

Finally, we return the result or handle errors:

	# Get the final message
           final_message = stream.get_final_message()

           return {
               "response": final_message,
               "question": question,
               "timestamp": datetime.datetime.now().isoformat(),
           }

   except Exception as e:
       print(f"❌ Error solving problem: {e}")
       return None

This function demonstrates several important concepts:

• Streaming support: We use client.messages.stream() instead of client.messages.create() to get real-time feedback as Claude works through the problem.
• Event handling: The streaming API sends different event types:
• content_block_start: When Claude begins writing text or using a tool
• content_block_delta: As content is being generated
• content_block_stop: When a content block is finished
• message_delta: When the entire message is complete
• Tool specification: We include the code execution tool in the tools array with the exact type "code_execution_20250522".
• Structured prompting: Our prompt clearly instructs Claude to use code execution and save any visualizations.

Step 4: Solve math problems with streaming code execution

When Claude creates files during code execution (like matplotlib plots), we need to extract their file IDs and download them locally.

The file extraction method navigates through the response structure:

def extract_files_from_response(self, response) -> List[str]:
   """Extract file IDs from Claude's response."""
   file_ids = []

   for item in response.content:
       if item.type == "code_execution_tool_result":
           content_item = item.content
          
           if isinstance(content_item, dict):
               if content_item.get("type") == "code_execution_result":
                   content_list = content_item.get("content", [])

Then we search for file IDs in the content:

  for file_item in content_list:
                       if isinstance(file_item, dict) and "file_id" in file_item:
                           file_ids.append(file_item["file_id"])

   return file_ids

The download process retrieves files and saves them locally:

def download_files(self, file_ids: List[str]) -> List[str]:
   """Download files created by code execution to local storage."""
   downloaded_files = []

   for file_id in file_ids:
       try:
           # Get file metadata and download content
           file_metadata = self.client.beta.files.retrieve_metadata(file_id)
           filename = file_metadata.filename
          
           file_content = self.client.beta.files.download(file_id)
           local_path = self.images_dir / filename
           file_content.write_to_file(str(local_path))

We track downloaded files and handle errors:

downloaded_files.append(str(local_path))
           print(f"✅ Downloaded: {filename}")

       except Exception as e:
           print(f"❌ Error downloading file {file_id}: {e}")

   return downloaded_files

• File extraction logic: The extract_files_from_response() method navigates through the response structure to find file IDs. Code execution results are nested in a specific format where files appear in the content array.
• File download process: The download_files() method:
• Gets metadata for each file (including the original filename)
• Downloads the file content using the Files API
• Saves files to our organized directory structure
• Returns a list of local file paths for later use