Soneto de Claude 4: Um guia prático para desenvolvedores

Com o lançamento do Claude Sonnet 4, os desenvolvedores agora têm acesso a novos recursos avançados, incluindo execução de código nativo, uma API de arquivos flexível e uso dinâmico de ferramentas. Esses recursos abrem possibilidades interessantes para a criação de aplicativos com tecnologia de IA que vão além das simples interações de texto.

Neste tutorial, mostrarei a você esses novos recursos, criando um agente baseado em Python que pode resolver problemas matemáticos avançados diretamente do seu terminal. Você aprenderá a usar a recém-introduzida ferramenta de execução de código nativo e a API de arquivos.

No final, você terá um agente em funcionamento com a tecnologia do Claude Sonnet 4 para analisar problemas, escrever e executar código Python e renderizar imagens como as apresentadas abaixo.

Confira o repositório do GitHub para este projeto e vejatodo o código para criar o aplicativo.

Se você está apenas começando sua jornada de desenvolvimento com LLMs como o Claude, este roteiro para desenvolvedores de IA descreveas ferramentas, as habilidades e as trilhas de aprendizagem essenciais para começar.

O que há de novo na API antrópica

Antes de entrarmos no tutorial, vamos dar uma olhada em todos os novos recursos lançados recentemente e disponíveis na API do Anthropic. Sinta-se à vontade para pular a página se você já estiver ciente delas.

Acho que todo o anúncio do Claude 4 pode serresumido nesta única imagem:

Os modelos Claude 4 (Opus e Sonnet 4) venceram a concorrência em tarefas de engenharia de software verificadas por uma margem significativa. O Anthropic conseguiu essa façanha introduzindo algumas mudanças importantes na forma como os modelos se comportam:

1. Tempos de execução longos: Ambos os modelos suportam várias horas de execução contínua de tarefas para resolver problemas com milhares de etapas.
2. Pensamento ampliado com o uso de ferramentas: Ambos os modelos agora podem usar ferramentas como a pesquisa na Web durante o raciocínio estendido, permitindo que o Claude alterne entre o raciocínio e o uso de ferramentas para melhorar as respostas.
3. Execução de ferramentas paralelas: Os modelos agora podem usar várias ferramentas simultaneamente, em vez de sequencialmente.
4. Instruções mais precisas após: A capacidade de direção aprimorada oferece aos usuários maior controle sobre as implementações e sobre como o Claude responde às instruções.
5. Recursos de memória aprimorados: Quando recebem acesso a arquivos locais, os modelos podem extrair e salvar fatos importantes para manter a continuidade e criar conhecimento tácito ao longo do tempo.
6. Redução do comportamento do atalho: Em comparação com as versões anteriores, ambos os modelos têm 65% menos probabilidade de usar atalhos ou brechas para concluir tarefas (consulte a publicação completa do anúncio para obter mais detalhes).

Além disso, como parte do anúncio da família de modelos Claude 4, a Anthropic adicionou quatro novos recursos para a criação de agentes de IA no site: a ferramenta de execução de código, a API Files, o conector MCP e o cache de prompt estendido. Essas ferramentas mudam a forma como os desenvolvedores podem criar aplicativos de IA.

Ferramenta de execução de código: Execute o código Python com segurança

A ferramenta de execução de código permite que o Claude execute o código Python em um ambiente seguro de sandbox. Em vez de apenas escrever sugestões de código, o Claude agora pode executar o código, analisar os resultados e iterar nas soluções.

Para usar a ferramenta de execução de código, adicione-a à sua matriz tools e inclua o cabeçalho beta necessário:

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"
   }]
)

Quando o Claude executa o código, a resposta contém o código gerado e os resultados da execução. Veja como você pode analisar os diferentes componentes:

# 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']}")

Limitações do sandbox: O ambiente de execução de código tem várias restrições de segurança incorporadas. O Claude é executado em um contêiner isolado, sem acesso à Internet, com recursos computacionais limitados (1 GB de RAM, 5 GB de espaço em disco e 1 CPU) e não pode acessar o sistema de arquivos local. O ambiente vem pré-instalado com bibliotecas populares como numpy, pandas, matplotlib e scipy, mas você não pode instalar pacotes adicionais durante a execução.

Arquivos API: Contexto de arquivo persistente para tarefas complexas

A API Files permite que você carregue documentos uma vez e faça referência a eles em várias conversas. Isso elimina a necessidade de incluir documentos grandes em cada solicitação de API.

Primeiro, carregue seu arquivo nos servidores do Anthropic:

# 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

Após o upload, faça referência ao arquivo em suas chamadas de API usando o tipo de conteúdo container_upload:

# 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"
   }]
)

Quando o Claude cria arquivos durante a execução do código (como gráficos ou dados processados), você pode extraí-los e baixá-los:

# 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")

Conector MCP: Conecte o Claude a qualquer fluxo de trabalho

O conector MCP oferece suporte ao protocolo de contexto de modelo diretamente para a API. Os MCPs permitem que o Claude se conecte a serviços externos, como bancos de dados, APIs e ferramentas de produtividade, sem código de integração personalizado.

Anteriormente, a conexão com os servidores MCP exigia a criação de uma infraestrutura de cliente. Agora, você pode simplesmente fornecer um URL de servidor MCP remoto na sua solicitação de API, e o Claude descobre automaticamente as ferramentas disponíveis, gerencia as conexões e lida com a autenticação.

Isso abre o acesso a um ecossistema crescente de servidores MCP de empresas como Zapier e Asana, permitindo que você crie agentes que possam ler seu calendário, atualizar ferramentas de gerenciamento de projetos ou integrar-se a centenas de outros serviços.

Primeiros passos com Claude Sonnet 4: Visão geral e configuração do projeto

Agora que entendemos os novos recursos da API, vamos criar nosso solucionador de problemas matemáticos interativo. Ele combinará os recursos de execução de código do Claude com o manuseio de arquivos para criar um assistente matemático completo.

Nosso aplicativo aceitará perguntas matemáticas em linguagem natural, executará código Python para resolvê-las, gerará visualizações e salvará relatórios abrangentes.

Para obter uma abordagem estruturada para criar projetos como esse, confira o programa Developing AI Applications (Desenvolvendo aplicativos de IA).

> Observação: Como dividiremos blocos de código longos com explicações, a indentação do código pode não ser totalmente precisa nos trechos. Por esse motivo, recomendamos que você abra o repositório do GitHub para esse projeto em uma guia separada enquanto o acompanha.

Etapa 0: Configure o ambiente do projeto Claude Sonnet 4

Antes de escrever qualquer código, vamos configurar nosso ambiente de desenvolvimento e dependências.

Crie um novo diretório para o seu projeto e configure os arquivos necessários:

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

Crie um arquivo requirements.txt com as dependências necessárias:

anthropic>=0.42.0

Instale as dependências:

pip install -r requirements.txt

Defina sua chave de API do Anthropic como uma variável de ambiente:

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

Etapa 1: Projetar a estrutura do aplicativo

Vamos começar criando a estrutura básica da nossa classe MathSolver. Essa classe tratará de toda a funcionalidade principal: Comunicação de API, gerenciamento de arquivos e interação com o usuário.

Primeiro, vamos configurar as importações e a estrutura básica:

#!/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

Agora vamos definir nossa estrutura de classe principal:

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

Por fim, adicionamos o gerenciamento de sessão e o ponto de entrada:

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

Essa estrutura nos dá um roteiro claro: inicialização, solução de problemas, manipulação de arquivos, geração de relatórios e interação com o usuário. Cada método tem uma responsabilidade específica em nosso pipeline de resolução de problemas matemáticos.

Criando um solucionador matemático com a execução de código do Claude Sonnet 4

Agora, vamos implementar a funcionalidade principal usando a ferramenta de execução de código do Claude e respostas de streaming.

Etapa 2: Inicializar o Claude com cabeçalhos de API seguros

Vamos implementar o método __init__() para lidar com a configuração do cliente da API e a criação do diretório.

Primeiro, lidamos com o gerenciamento de chaves de API:

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"
           )

Em seguida, configuramos o cliente Anthropic com os cabeçalhos beta necessários:

# 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"
       },
   )

Por fim, criamos a estrutura do diretório de saída:

# 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}")

Essa inicialização faz três coisas importantes:

1. Gerenciamento de chaves de API: Verifica primeiro a chave nas variáveis de ambiente e, em seguida, volta para um parâmetro.
2. Configuração do cliente: Cria um cliente Anthropic com cabeçalhos beta para execução de código e API de arquivos.
3. Estrutura do diretório: Cria pastas organizadas para armazenar imagens e relatórios.

Etapa 3: Escreva a função principal do solucionador

O método solve_problem() é o coração do nosso aplicativo. Ele envia solicitações ao Claude com suporte a streaming.

Vamos começar com a assinatura da função e a configuração inicial:

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}")

Lidamos com diferentes tipos de eventos de streaming:

	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}")

Por fim, retornamos o resultado ou tratamos os erros:

	# 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

Essa função demonstra vários conceitos importantes:

• Suporte a streaming: Usamos o site client.messages.stream() em vez do client.messages.create() para obter feedback em tempo real à medida que Claude resolve o problema.
• Tratamento de eventos: A API de streaming envia diferentes tipos de eventos:
• content_block_start: Quando Claude começa a escrever um texto ou a usar uma ferramenta
• content_block_delta: Como o conteúdo está sendo gerado
• content_block_stop: Quando um bloco de conteúdo é concluído
• message_delta: Quando a mensagem inteira estiver concluída
• Especificação da ferramenta: Incluímos a ferramenta de execução de código na matriz tools com o tipo exato "code_execution_20250522".
• Solicitação estruturada: Nosso prompt instrui claramente o Claude a usar a execução de código e salvar todas as visualizações.

Etapa 4: Resolva problemas matemáticos com a execução de código em fluxo contínuo

Quando o Claude cria arquivos durante a execução do código (como os gráficos do matplotlib), precisamos extrair os IDs dos arquivos e baixá-los localmente.

O método de extração de arquivos navega pela estrutura de resposta:

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", [])

Em seguida, procuramos IDs de arquivos no conteúdo:

  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

O processo de download recupera os arquivos e os salva localmente:

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))

Nós programamos os arquivos baixados e tratamos os erros:

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

• Lógica de extração de arquivos: O método extract_files_from_response() navega pela estrutura de resposta para localizar IDs de arquivos. Os resultados da execução do código são aninhados em um formato específico em que os arquivos aparecem na matriz content.
• Processo de download de arquivos: O método download_files():
• Obtém metadados para cada arquivo (incluindo o nome do arquivo original)
• Faz o download do conteúdo do arquivo usando a API Files
• Salva arquivos em nossa estrutura de diretórios organizada
• Retorna uma lista de caminhos de arquivos locais para uso posterior