Otros SDK y mejores prácticas de compatibilidad con OpenAI
Una lista de verificación para elegir entre un SDK nativo de Go, Java, C#, PHP o Ruby y el atajo de migración compatible con OpenAI, y para usar cada uno bien una vez que lo hayas elegido.
Cómo usar esta lista de verificación
- Trabaja primero en la sección A si aún no has elegido una ruta de integración; las secciones B-D asumen que ya lo has hecho.
- Revisa esta lista cada vez que agregues un nuevo idioma a un backend políglota, o cuando un prototipo de capa de compatibilidad esté a punto de convertirse en una característica permanente.
- Trata los elementos sin marcar como preguntas abiertas a resolver antes de que una integración de Claude pase a producción, no como pulido opcional.
A - Elección de una ruta de integración
- Haz coincidir el SDK con el idioma del servicio, no con la preferencia personal. Un servicio de Go debe usar
anthropic-sdk-go; una aplicación Ruby debe usar el SDK de Ruby, incluso si el lenguaje favorito del equipo está en otro lugar. - Usa la capa de compatibilidad de OpenAI solo como un puente, no como un destino. Está diseñada para una migración rápida y pruebas lado a lado, no como la ruta de integración recomendada a largo plazo.
- Verifica la referencia de mapeo de parámetros antes de migrar una base de código que utiliza parámetros poco comunes de OpenAI. Las penalizaciones de muestreo, las solicitudes de completado múltiple y las formas de llamada a funciones son los lugares más probables para encontrar una brecha.
- Planifica la ruta de actualización desde la capa de compatibilidad desde el principio. Decide, antes de comenzar, qué condición ("una vez que validemos la calidad de la salida", "una vez que el prototipo reciba tráfico real") activa el cambio al SDK nativo.
- Acepta que un backend políglota puede usar varios SDK oficiales a la vez. No hay un impuesto de compatibilidad entre SDK; una pasarela Go y una malla de servicios Java pueden llamar a Claude de forma nativa sin ninguna sobrecarga de coordinación entre ellas.
B - Trabajar con un SDK nativo (Go, Java, C#, PHP, Ruby)
- Construye el cliente una vez y reutilízalo. Construir un nuevo cliente por solicitud (especialmente en Go, Java y C#) descarta la agrupación de conexiones y agrega latencia evitable.
- Lee la clave API de la configuración del entorno, no de cadenas codificadas. El constructor del cliente de cada SDK acepta una clave API obtenida por convención de
ANTHROPIC_API_KEY; mantenla fuera del control de código fuente. - Establece un
max_tokensexplícito para cada solicitud. Ninguno de los cinco SDK proporciona un valor predeterminado implícito sensato; ajústalo a la longitud de respuesta esperada. - Haz coincidir el manejo de errores con la convención propia del idioma, no con los hábitos de otro idioma. Verifica los errores devueltos en Go, captura excepciones tipificadas en Java y C#, y maneja las excepciones lanzadas en PHP y Ruby, de la manera que el código nativo de ese idioma lo haría normalmente.
- Trata una razón de parada
tool_usecomo "esperando", no como "hecho". Ejecuta la herramienta solicitada, luego envía untool_resulten una llamada de seguimiento antes de considerar el intercambio como completo.
C - Uso idiomático de herramientas en todos los idiomas
- Usa la forma de esquema natural de cada idioma para las definiciones de herramientas. Estructuras en Go, constructores en Java, objetos tipificados en C#, matrices asociativas en PHP, hashes en Ruby; no luches contra los modismos del idioma para que cinco SDK se vean idénticos.
- Recuerda que el protocolo de red es idéntico independientemente de la sintaxis. Un esquema de herramienta construido como una estructura Go y uno construido como un hash Ruby producen el mismo JSON Schema en la red; depura a nivel de protocolo cuando algo parezca incorrecto, no solo a nivel de idioma.
- Haz coincidir cada
tool_resultcon su ID detool_usede origen. Este requisito es idéntico en los cinco SDK; un ID faltante o que no coincide produce una solicitud rechazada sin importar qué idioma la envió. - Valida la forma de entrada de la herramienta en el extremo receptor, especialmente en PHP y Ruby. Ninguno de los dos idiomas verifica el tipo de la solicitud o respuesta en tiempo de compilación, así que agrega tu propia validación antes de confiar en campos como la entrada de una herramienta.
D - Streaming en Java y C#
- Consume el stream de Java a través de
try-with-resources.StreamResponsemantiene una conexión HTTP abierta; no cerrarla provoca fugas de conexión bajo carga sostenida. - Mantén las llamadas de streaming de C# completamente asíncronas de principio a fin. Usa
await foreachdentro de una cadena de métodosasync; llamar a.Resulto.Wait()en una llamada de streaming puede provocar interbloqueos y anula el propósito deIAsyncEnumerable. - No asumas que los deltas de texto se alinean con los límites de palabras o frases. Almacena en búfer y renderiza incrementalmente en ambos idiomas sin asumir que un delta termina limpiamente.
- Acumula JSON parcial para la entrada de
tool_usetransmitida antes de analizarla. Los argumentos de un bloquetool_usepueden llegar como fragmentos de JSON incompletos; analiza solo una vez que se active el evento de parada del bloque. - Verifica la razón de parada final, no solo el último delta de texto recibido. Una respuesta que se detuvo temprano debido a
max_tokensse ve similar a una completa si solo estás observando el texto, así que lee explícitamente la razón de parada del evento terminal.
Cuando hayas terminado
Trabaja en la sección A una vez por cada nueva integración, y mantén B-D como una referencia continua mientras construyes contra el SDK que el servicio termine usando.
Si más de un par de elementos en la sección A permanecen sin marcar para un servicio que ahora se ejecuta en producción en la capa de compatibilidad, eso es una señal de que la migración a un SDK nativo está atrasada, no opcional.
Preguntas frecuentes
¿Debo empezar con la capa de compatibilidad de OpenAI o con un SDK nativo?
Comienza con la capa de compatibilidad solo si ya tienes una integración de OpenAI funcionando y deseas una prueba o migración rápida. Si estás construyendo desde cero, ve directamente al SDK nativo para tu idioma; no hay ningún beneficio de la capa de compatibilidad para un proyecto nuevo.
¿Está mal dejar un servicio en la capa de compatibilidad de forma permanente?
No está mal automáticamente, pero es un compromiso: estás limitado a la superficie de parámetros con forma de OpenAI y heredas sus brechas de traducción. Si los parámetros que usas se mapean limpiamente y el equipo no tiene ancho de banda para migrar, puede ser una opción aceptable a largo plazo.
¿Cuál es el error más común que cometen los equipos al elegir entre SDK?
Elegir un idioma para la integración basándose en la preferencia del equipo en lugar de en lo que está escrito el servicio, lo que luego obliga a un salto innecesario entre idiomas solo para llamar a Claude.
¿Por qué el manejo de errores de Go difiere del de Java y C# en esta lista de verificación?
Porque cada SDK sigue la convención de su lenguaje anfitrión: Go devuelve errores como valores, mientras que Java y C# lanzan excepciones tipificadas. Esto no es una inconsistencia en los SDK de Claude; es que cada SDK coincide con los modismos que los desarrolladores de ese idioma ya esperan.
¿Necesito preocuparme por fugas de conexión en todos los SDK, o solo en Java?
El StreamResponse de Java es el caso más explícito ya que es un AutoCloseable que debes cerrar tú mismo. Go y C# gestionan el ciclo de vida de la conexión subyacente de forma más implícita a través de sus patrones de iterador y stream asíncrono, pero reutilizar un solo cliente de larga duración (en lugar de construir uno por solicitud) es importante en todos ellos.
¿Cuál es la mayor brecha a tener en cuenta al migrar código de llamada a herramientas a través de la capa de compatibilidad?
La discrepancia de forma entre los parámetros de llamada a funciones de OpenAI y el protocolo tool_use de Claude. Prueba los flujos de llamada a herramientas específicamente después de migrar, en lugar de asumir que se comportan de manera idéntica solo porque la generación de texto plano funcionó.
¿Puedo mezclar la capa de compatibilidad y un SDK nativo en la misma base de código?
Sí, temporalmente, como estrategia de migración: mantén la capa de compatibilidad en rutas de llamada estables y de bajo riesgo mientras migras primero las rutas de llamada de mayor valor o con muchas herramientas al SDK nativo.
¿Qué tan estricto debo ser al hacer coincidir la sintaxis del esquema con los modismos de cada idioma?
Estricto. Luchar contra las convenciones naturales de un idioma (como intentar forzar esquemas estrictamente tipificados en PHP o Ruby) agrega fricción sin agregar seguridad, ya que el protocolo de red es idéntico independientemente de cuán idiomáticamente escribas el código del lado del cliente.
¿Qué debería desencadenar el abandono de la capa de compatibilidad de forma definitiva?
Cualquiera de las siguientes opciones: has validado que Claude es el modelo adecuado para producción, necesitas una capacidad específica de Claude que no esté expuesta a través de la superficie con forma de OpenAI, o has encontrado una brecha de mapeo de parámetros que afecta a una característica real.
¿Existe un costo de rendimiento por usar un SDK nativo en lugar de la capa de compatibilidad?
No de forma significativa por el SDK en sí; ambos se comunican por HTTP con la infraestructura de Anthropic. El beneficio práctico del SDK nativo es una superficie de parámetros más completa y un manejo idiomático de errores y streaming, no velocidad bruta.
Relacionado
- Más allá de Python y TypeScript: Los otros SDK oficiales de Claude - la descripción general conceptual detrás de la guía de la sección A
- Migración de una base de código del SDK de OpenAI a Claude - el recorrido completo de migración detrás de las secciones A y B
- Referencia de mapeo de parámetros de la capa de compatibilidad de OpenAI - el detalle parámetro por parámetro detrás de la guía de mapeo de la sección A
- Uso idiomático de herramientas en Go, Java, C#, PHP y Ruby - la comparación completa detrás de la sección C
- Respuestas en streaming en Java y C# con los SDK oficiales - el recorrido completo detrás de la sección D
Versiones de pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y los SDK oficiales actuales para Go, Java, C#, PHP y Ruby. Los nombres de los modelos, las versiones de los SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.