Em 14 de agosto de 2026, às 23:48 UTC, a OpenAI lançou a versão 3.1.0 do SDK openai-python. A atualização traz duas mudanças estruturais para quem desenvolve sistemas baseados em chamadas de ferramentas e agentes: um modelo discriminado de erros para o Model Context Protocol (MCP) e roteamento sequencial de eventos assíncronos via WebSockets com stream_id.
O problema da representação de erros no Tool Calling
Na orquestração de agentes e pipelines de tool calling, a resposta de sucesso de uma ferramenta é estruturada via JSON Schema. No entanto, a tipagem de falhas gerava ambiguidade no cliente: o SDK anterior previa formalmente uma variante em texto plano para representar erros de chamadas MCP, embora a própria API de backend não retornasse nem aceitasse strings livres nesse canal.
Essa discrepância no esquema trazia desafios práticos de engenharia:
- Dificuldade de categorização programática: O código cliente precisava lidar com uma tipagem excessivamente permissiva no SDK, sem a garantia em tempo de compilação de que os erros chegariam estruturados em objetos tipados.
- Tratamento de exceções não padronizado: Sem um discriminador explícito no modelo de dados, bibliotecas e middlewares de agentes dependiam de checagens manuais de tipo para rotear falhas de ferramentas.
O PR #3617 resolve essa divergência removendo a variante em string anteriormente anunciada e estabelecendo uma união discriminada pelo campo type.
A estrutura do McpToolCallError no SDK 3.1.0
No módulo openai.types.responses.mcp_tool_call_error, o SDK define o modelo McpToolCallError composto por três variantes estritas:
McpProtocolError: Representa falhas do protocolo MCP. Contémcode: int,message: stretype: Literal["mcp_protocol_error"].McpToolExecutionError: Representa falhas originadas durante a execução da ferramenta no servidor MCP. Contémcontent: objectetype: Literal["mcp_tool_execution_error"].HTTPError: Representa falhas na camada de transporte HTTP. Contémcode: int,message: stretype: Literal["http_error"].
No esquema de parâmetros de ferramentas remotos (ToolParam), o SDK exige server_label e um endereço de destino (como server_url), permitindo opcionalmente restringir as ferramentas disponíveis com allowed_tools.
from openai import OpenAI
from openai.types.responses import McpToolCallError
client = OpenAI()
response = client.responses.create(
model="gpt-5",
tools=[
{
"type": "mcp",
"server_label": "analytics_server",
"server_url": "https://mcp.internal.empresa.com/v1",
"allowed_tools": ["query_logs"],
}
],
input="Verifique os logs de tráfego dos últimos 30 minutos.",
)
# Inspecionando itens de saída da resposta para tratar falhas estruturadas
for item in response.output:
if item.type == "mcp_call" and item.error:
error: McpToolCallError = item.error
if error.type == "mcp_protocol_error":
# Falha de protocolo RPC (código numérico e mensagem descritiva)
print(f"Erro de protocolo [{error.code}]: {error.message}")
elif error.type == "mcp_tool_execution_error":
# Exceção emitida pelo código interno da ferramenta remota
print(f"Erro na execução da tool: {error.content}")
elif error.type == "http_error":
# Falha de transporte HTTP (código de status e mensagem de erro)
print(f"Falha de transporte HTTP [{error.code}]: {error.message}")
Com essa estrutura discriminada, a arquitetura da aplicação pode estabelecer estratégias condicionais de tratamento: implementar retentativas com backoff ao receber http_error, ou repassar o content de um mcp_tool_execution_error ao contexto do modelo para permitir correção informada de parâmetros.
Roteamento FIFO em WebSockets com stream_id
Outra novidade introduzida no release é o suporte a identificadores de fluxo (stream_id) em conexões WebSocket da API Responses, adicionado pelo PR #3612.
Em aplicações que utilizam streaming bidirecional em tempo real, múltiplos eventos de resposta podem trafegar pela mesma conexão WebSocket.
Conforme especificado no PR:
- O campo
stream_idpassa a ser suportado como metadado de roteamento em eventos do cliente e do servidor. - Eventos que compartilham o mesmo
stream_idtêm garantia de processamento em ordem sequencial estrita (FIFO — First-In, First-Out) no servidor. - As mensagens de resposta do servidor refletem o identificador correspondente, permitindo que a aplicação cliente associe cada fragmento de stream ao seu respectivo canal de execução.
Novidades complementares no tooling Python: Astral uv 0.12.5
No mesmo dia do release da OpenAI, a Astral publicou a versão uv 0.12.5 com melhorias direcionadas à gestão de dependências e auditoria de pacotes:
- Seleção de índices por nome (
index-by-name): O recurso em modo preview permite que flags como--indexe--default-indexselecionem índices de pacotes configurados declarativamente por nome, facilitando o uso de repositórios privados em conjunto com o registro padrão. - Hashes e URLs no CycloneDX SBOM: O comando de exportação de Software Bill of Materials (SBOM) no formato CycloneDX passa a incluir por padrão as URLs e os hashes de distribuição de cada artefato instalado, simplificando processos de verificação de integridade e conformidade de supply chain.
Essas adições no ferramental Python auxiliam equipes de engenharia a empacotar ambientes com dependências fixadas e auditáveis ao implantar serviços de agentes em produção.
O que isso muda na arquitetura de ferramentas e agentes de código
Para qualquer arquitetura de software orientada a agentes que integre servidores MCP — como assistentes de programação e automações no estilo MaxVision Code —, a padronização de erros traz maior previsibilidade à camada de integração.
Ao orquestrar ferramentas externas via protocolo MCP, a capacidade de identificar programaticamente se uma falha decorre da camada de transporte HTTP, do protocolo de comunicação ou da execução interna da ferramenta permite que o orquestrador aplique fluxos de recuperação sob medida para cada tipo de exceção.
Tratar tool calling com interfaces discriminadas e fluxos ordenados via stream_id aproxima a construção de agentes dos padrões de estabilidade exigidos em sistemas distribuídos de produção.
Perguntas Frequentes
Quais tipos de erro compõem o McpToolCallError no openai-python 3.1.0?
O McpToolCallError é uma união discriminada composta por McpProtocolError (código e mensagem de erro do protocolo MCP), McpToolExecutionError (conteúdo retornado pela ferramenta em caso de falha de execução) e HTTPError (código e mensagem de falhas na camada de transporte HTTP).
Como o SDK 3.1.0 tratou a antiga variante de erro em string?
O PR #3617 removeu a variante em string que constava anteriormente na especificação do SDK, já que a API de backend nem retornava nem aceitava strings livres para erros de chamadas MCP, unificando a representação no modelo discriminado McpToolCallError.
O que muda com o suporte a stream_id no Responses WebSocket?
Eventos que compartilham o mesmo stream_id recebem garantia de processamento em ordem FIFO (First-In, First-Out) no servidor, e as mensagens de resposta ecoam esse identificador, permitindo que o cliente demultiplexe fluxos simultâneos.
Quais APIs foram marcadas como depreciadas na versão 3.1.0?
O PR #3610 introduziu avisos formais de depreciação para as APIs de vídeo do Sora no SDK, antecipando o encerramento do serviço programado para setembro de 2026.
Conclusão
O lançamento do openai-python v3.1.0 reforça que a confiabilidade de sistemas autônomos depende de contratos claros de comunicação. A introdução de erros discriminados para o Model Context Protocol e o ordenamento FIFO de streams em WebSockets fornecem os blocos fundamentais para construir agentes que lidam com exceções de forma previsível.
Para desenvolvedores e times de engenharia de software, a atualização oferece interfaces mais sólidas para gerenciar falhas de ferramentas externas, auditar dependências e estruturar pipelines de IA em produção.
