Code Interpreter: Executar Código na API
Nesta página
Atualizado em 2 de novembro de 2026 com base no guia oficial do Code Interpreter e no SDK
openai: a ferramenta requer um parâmetrocontainer(omisso em todos os exemplos anteriores, o que teria causado falhas), os ficheiros gerados aparecem nas anotaçõescontainer_file_citatione são transferidos através da API de Contentores (não viaclient.files.content), e os resultados das chamadas denominam-seoutputs(nãoresults). As partes de texto de entrada utilizam o tipoinput_text. Os ficheiros anexados a uma mensagem são carregados com o propósitouser_data, que a OpenAI recomenda para entradas do modelo (File inputs). Fontes: Code Interpreter · File inputs.
Code Interpreter: Executar Código na API
Um modelo de linguagem prevê texto; não calcula. Peça-lhe a raiz quadrada de 1764 e ele produzirá o resultado mais provável com base no seu treino — muitas vezes correto, por vezes errado, sem forma de distinguir a diferença. O Code Interpreter elimina esta incerteza ao fornecer ao modelo um interpretador Python: ele escreve o cálculo, executa-o e devolve um resultado obtido, não um palpite.
A mudança é mais profunda do que parece. O modelo vê o resultado do seu próprio código, incluindo erros, pelo que pode autocorrigir-se e tentar novamente. Num ficheiro de dados cuja estrutura exata ninguém conhece, este ciclo supera qualquer instrução pré-escrita.
Ativar o Code Interpreter
Ativa-o adicionando a ferramenta ao array tools — nada para instalar, nenhum ambiente para aprovisionar. O modelo decide quando escrever código: responde diretamente a perguntas factuais, mas muda para a execução em caso de cálculos ou manipulação de dados.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Calculate the Fibonacci sequence up to the 20th term",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
print(response.output_text)
O modelo escreve o código Python, executa-o numa sandbox e integra os resultados na sua resposta.
Inspecionar o Código Executado
Adquira o hábito de ler este código, pelo menos durante o desenvolvimento. É a única forma de distinguir um bom resultado de um que esteja certo por acaso: uma média calculada ignorando silenciosamente valores em falta é numericamente correta, mas analiticamente falsa. A resposta não lho dirá; o código sim.
A resposta contém o código gerado e os seus resultados:
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the square root of 1764? Verify by squaring the result.",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
include=["code_interpreter_call.outputs"], # to receive produced logs and images
)
for item in response.output:
if item.type == "code_interpreter_call":
print("--- Executed Code ---")
print(item.code)
print("--- Outputs ---")
for output in item.outputs or []:
print(output.logs if output.type == "logs" else output.url)
Fornecer Ficheiros como Entrada
A ferramenta entrega todo o seu valor quando trabalha com ficheiros. Carrega o ficheiro, referencia-o na chamada e o modelo abre-o efetivamente — lê as colunas reais, os tipos reais e os valores atípicos reais, em vez de raciocinar sobre uma descrição que possa ter fornecido.
# Upload the file
with open("sales_2025.csv", "rb") as f:
file_obj = client.files.create(file=f, purpose="user_data")
# Use Code Interpreter with the file
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Analyze this sales file. "
"Give me the total by category and the best-performing month."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
print(response.output_text)
Recuperar Ficheiros Gerados
O caminho inverso também funciona: o código produz um CSV limpo, um gráfico ou um livro Excel, e esses ficheiros são-lhe devolvidos. Permanecem no contentor, e a mensagem de resposta cita-os nas suas anotações do tipo container_file_citation, incluindo o ID do contentor, o ID do ficheiro e o nome do ficheiro. De seguida, transfere-os através da API de Contentores. Duas pequenas funções, reutilizadas em lições posteriores, encapsulam este fluxo:
def generated_files(response):
"""Files created by Code Interpreter, cited in message annotations."""
for item in response.output:
if item.type == "message":
for part in item.content:
for ann in getattr(part, "annotations", None) or []:
if ann.type == "container_file_citation":
yield ann
def download(client, ann, path):
"""Downloads a file from the container and returns its local path."""
content = client.containers.files.content.retrieve(ann.file_id, container_id=ann.container_id)
with open(path, "wb") as out:
out.write(content.read())
return path
Os ficheiros que fornece como entrada (input_file) são copiados automaticamente para o contentor: não precisa de carregar mais nada.
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Create a chart of sales by month "
"and export the cleaned data as a CSV."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
# Retrieve generated files
for ann in generated_files(response):
print(f"Generated file: {ann.filename}")
download(client, ann, ann.filename)
Contentor e Ambiente
Conhecer as regras do contentor poupa tempo na depuração do que não pode funcionar. De acordo com a documentação da OpenAI:
- é uma máquina virtual totalmente isolada (sandbox) onde o modelo executa Python;
- a ferramenta requer um parâmetro
container:{"type": "auto"}cria um contentor (ou reutiliza um de uma chamada anterior presente no contexto), enquanto um ID obtido viaclient.containers.create(...)força um contentor específico; - a memória é definida com
memory_limit:1g(padrão),4g,16gou64g, sendo os níveis superiores faturados às taxas de ferramentas integradas; - um contentor expira após 20 minutos de inatividade; os seus dados são então perdidos, por isso transfira quaisquer ficheiros que queira manter enquanto estiver ativo.
Não conte com acesso à rede a partir do código: forneça dados como entrada ou delegue a pesquisa na ferramenta Web Search.
# Example: the model can use pandas directly
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Load this CSV with pandas, "
"calculate descriptive statistics, and identify outliers."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
Encadear Múltiplas Execuções
Execuções sucessivas partilham a mesma sessão: variáveis, DataFrames e importações do primeiro bloco permanecem disponíveis no seguinte, exatamente como num notebook. O modelo aproveita isto naturalmente — carrega, inspeciona e depois processa — tornando possível a análise em várias etapas sem recarregar tudo em cada fase.
response = client.responses.create(
model="gpt-5.6-terra",
input="1. Generate 1000 random points from a normal distribution. "
"2. Calculate the mean and standard deviation. "
"3. Create a histogram. "
"4. Perform a Shapiro-Wilk normality test.",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
# The model executes 4 code blocks sequentially
# Each block has access to variables from previous ones
Combinar com Outras Ferramentas
A combinação mais útil associa uma fonte de dados à capacidade de a processar: o File Search encontra a passagem relevante nos seus documentos, o Web Search traz dados de mercado e o Code Interpreter compara os dois numa tabela ou gráfico. Nenhuma destas ferramentas pode fazer o trabalho das outras.
response = client.responses.create(
model="gpt-5.6-terra",
input="Search the web for French GDP data from the last 10 years, "
"then create a trend chart with a linear regression.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter", "container": {"type": "auto"}}
]
)
Padrão: Pipeline de Análise Completa
O exemplo final encadeia tudo o que foi referido acima num caso realista: um ficheiro de entrada, análise em várias etapas e produtos finais. Foque-se especialmente no formato do prompt — numerado, explícito sobre o resultado esperado — porque isso, muito mais do que o código Python que o acompanha, determina a qualidade do resultado.
def analyze_data(file_path: str, questions: list[str]) -> dict:
"""Data analysis pipeline with Code Interpreter."""
# Upload
with open(file_path, "rb") as f:
file_obj = client.files.create(file=f, purpose="user_data")
results = {}
for question in questions:
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": question},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
instructions="Write clean, commented Python code. "
"Display intermediate results."
)
results[question] = response.output_text
return results
# Usage
results = analyze_data("sales.csv", [
"Give descriptive statistics for each numeric column",
"What are the top 5 best-selling products?",
"Is there seasonality in sales?"
])
Pontos-chave
- O Code Interpreter executa Python num contentor isolado; o parâmetro
containeré obrigatório ({"type": "auto"}ou um ID) - Os ficheiros fornecidos como
input_filesão copiados automaticamente para o contentor - Os ficheiros gerados são citados como
container_file_citatione transferidos viaclient.containers.files.content.retrieve - Um contentor expira após 20 minutos de inatividade: transfira o que quiser manter
- Combine com Web Search e File Search para uma análise enriquecida