Claude API

Fuente: Contenido adaptado de anthropics/skills (MIT).

Esta habilidad le ayuda a crear aplicaciones basadas en LLM con Claude. Elija la superficie adecuada según sus necesidades, detecte el idioma del proyecto y luego lea la documentación específica del idioma correspondiente.

Antes de comenzar

Escanee el archivo de destino (o, si no hay un archivo de destino, el mensaje y el proyecto) en busca de marcadores de proveedores no antrópicos:import openai,from openai,langchain_openai,OpenAI(,gpt-4,gpt-5, nombres de archivos comoagent-openai.pyo*-generic.py, o cualquier instrucción explícita para mantener el código neutral respecto al proveedor. Si encuentra alguno, deténgase y dígale al usuario que esta habilidad produce el código SDK de Claude/Anthropic; pregunte si quieren cambiar el archivo a Claude o si quieren una implementación que no sea Claude. No edite un archivo que no sea Anthropic con llamadas al SDK de Anthropic.

Requisito de salida

Cuando el usuario le pide que agregue, modifique o implemente una característica de Claude, su código debe llamar a Claude a través de uno de:

1. El SDK oficial de Anthropic para el idioma del proyecto (anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Este es el valor predeterminado siempre que exista un SDK compatible para el proyecto.
2. HTTP sin formato (curl,requests,fetch,httpx, etc.): solo cuando el usuario solicita explícitamente cURL/REST/HTTP sin formato, el proyecto es un proyecto shell/cURL o el idioma no tiene un SDK oficial.

Nunca mezcle los dos: no utilicerequests/fetchen un proyecto de Python o TypeScript solo porque se siente más liviano. Nunca recurra a las cuñas compatibles con OpenAI.

Nunca adivine el uso del SDK. Los nombres de funciones, nombres de clases, espacios de nombres, firmas de métodos y rutas de importación deben provenir de documentación explícita, ya sea los archivos{lang}/en esta habilidad o los repositorios oficiales del SDK o los enlaces de documentación enumerados enshared/live-sources.md. Si el enlace que necesita no está documentado explícitamente en los archivos de habilidades, obtenga Web del repositorio de SDK correspondiente deshared/live-sources.mdantes de escribir el código. No infieras las API de Ruby/Java/Go/PHP/C# a partir de formas de cURL o del SDK de otro idioma.

Valores predeterminados

Salvo que el usuario solicite lo contrario:

Para la versión del modelo Claude, utilice Claude Opus 4.7, al que puede acceder a través de la cadena de modelo exactaclaude-opus-4-7. Utilice de forma predeterminada el pensamiento adaptativo (thinking: {type: "adaptive"}) para cualquier cosa remotamente complicada. Y, por último, utilice la transmisión de forma predeterminada para cualquier solicitud que pueda implicar una entrada larga, una salida larga o unmax_tokensalto; esto evita que se alcancen los tiempos de espera de la solicitud. Utilice el asistente.get_final_message()/.finalMessage()del SDK para obtener la respuesta completa si no necesita manejar eventos de transmisión individuales.

Subcomandos

Si la Solicitud de usuario en la parte inferior de este mensaje es una cadena de subcomando simple (sin prosa), busque en cada tabla de Subcomandos de este documento, incluidas las de las secciones adjuntas a continuación, y siga directamente la columna Acción correspondiente. Esto permite a los usuarios invocar flujos específicos a través de/claude-api <subcommand>. Si ninguna tabla del documento coincide, trate la solicitud como prosa normal.

Detección de idioma

Antes de leer los ejemplos de código, determine en qué idioma está trabajando el usuario:

1. Mire los archivos del proyecto para inferir el idioma:

   • *.py,requirements.txt,pyproject.toml,setup.py,Pipfile-> Python - leído desdepython/
   • *.ts,*.tsx,package.json,tsconfig.json-> TypeScript - leído desdetypescript/
   • *.js,*.jsx(no hay archivos.tspresentes) -> TypeScript - JS usa el mismo SDK, leído desdetypescript/
   • *.java,pom.xml,build.gradle-> Java - leído desdejava/
   • *.kt,*.kts,build.gradle.kts-> Java - Kotlin usa el SDK de Java, leído desdejava/
   • *.scala,build.sbt-> Java - Scala usa el SDK de Java, leído desdejava/
   • *.go,go.mod-> Ir - leer desdego/
   • *.rb,Gemfile-> Ruby - leído desderuby/
   • *.cs,*.csproj-> C# - leído desdecsharp/
   • *.php,composer.json-> PHP - leído desdephp/

2. Si se detectan varios idiomas (por ejemplo, archivos Python y TypeScript):

   • Verifique a qué idioma se relaciona el archivo o la pregunta actual del usuario
   • Si aún tiene dudas, pregunte: "Detecté archivos Python y TypeScript. ¿Qué lenguaje está utilizando para la integración de Claude API?"

3. Si no se puede inferir el idioma (proyecto vacío, sin archivos fuente o idioma no compatible):

   • Utilice AskUserQuestion con opciones: Python, TypeScript, Java, Go, Ruby, cURL/HTTP sin formato, C#, PHP
   • Si AskUserQuestion no está disponible, utilice de forma predeterminada ejemplos de Python y tenga en cuenta: "Mostrando ejemplos de Python. Avíseme si necesita un idioma diferente".

4. Si se detecta un idioma no compatible (Rust, Swift, C++, Elixir, etc.):

   • Sugiera ejemplos de cURL/HTTP sin formato decurl/y tenga en cuenta que pueden existir SDK de la comunidad
   • Oferta para mostrar ejemplos de Python o TypeScript como implementaciones de referencia

5. Si el usuario necesita ejemplos de cURL/HTTP sin formato, lea decurl/.

Compatibilidad con funciones específicas del idioma

¿Qué superficie debo utilizar?

Árbol de decisión

What does your application need?

0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry?
    Yes -> Claude API (+ tool use for agents) - Managed Agents is 1P only.
   No -> continue.

1. Single LLM call (classification, summarization, extraction, Q&A)
    Claude API - one request, one response

2. Do you want Anthropic to run the agent loop and host a per-session
   container where Claude executes tools (bash, file ops, code)?
    Yes -> Managed Agents - server-managed sessions, persisted agent configs,
       SSE event stream, Skills + MCP, file mounts.
       Examples: "stateful coding agent with a workspace per task",
                 "long-running research agent that streams events to a UI",
                 "agent with persisted, versioned config used across many sessions"

3. Workflow (multi-step, code-orchestrated, with your own tools)
    Claude API with tool use - you control the loop

4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
    Claude API agentic loop (maximum flexibility)

¿Debería crear un agente?

Antes de elegir el nivel de agente, verifique los cuatro criterios:

• Complejidad: ¿la tarea consta de varios pasos y es difícil especificarla completamente de antemano? (por ejemplo, "convertir este documento de diseño en un PR" frente a "extraer el título de este PDF")
• Valor: ¿El resultado justifica un mayor costo y latencia?
• Viabilidad - ¿Claude es capaz de realizar este tipo de tarea?
• Costo del error - ¿Se pueden detectar y recuperar los errores? (pruebas, revisión, reversión)

Si la respuesta a cualquiera de estas preguntas es "no", quédese en un nivel más simple (llamada única o flujo de trabajo).

Arquitectura

Todo pasa porPOST /v1/messages. Las herramientas y las restricciones de salida son características de este único punto final, no API independientes.

Herramientas definidas por el usuario: usted define las herramientas (a través de decoradores, esquemas Zod o JSON sin formato) y el ejecutor de herramientas del SDK se encarga de llamar a la API, ejecutar sus funciones y realizar un bucle hasta que Claude termine. Para un control total, puedes escribir el bucle manualmente.

Herramientas del lado del servidor: herramientas alojadas en Anthropic que se ejecutan en la infraestructura de Anthropic. La ejecución del código es completamente del lado del servidor (declárelo entools, Claude ejecuta el código automáticamente). El uso de la computadora puede ser alojado en un servidor o autohospedado.

Salidas estructuradas: restringe el formato de respuesta de la API de mensajes (output_config.format) y/o la validación de parámetros de la herramienta (strict: true). El enfoque recomendado esclient.messages.parse(), que valida las respuestas con respecto a su esquema automáticamente. Nota: el antiguo parámetrooutput_formatestá en desuso; useoutput_config: {format: {...}}enmessages.create().

Puntos finales de soporte: lotes (POST /v1/messages/batches), archivos (POST /v1/files), recuento de tokens y modelos (GET /v1/models,GET /v1/models/{id}- capacidad en vivo/descubrimiento de ventana contextual) alimentan o admiten solicitudes de API de mensajes.

Modelos actuales (en caché: 2026-04-15)

SIEMPRE useclaude-opus-4-7a menos que el usuario nombre explícitamente un modelo diferente. Esto no es negociable. No utiliceclaude-sonnet-4-6,claude-sonnet-4-5ni ningún otro modelo a menos que el usuario diga literalmente "use soneto" o "use haiku". Nunca bajes de categoría por el costo: esa es la decisión del usuario, no la tuya.

CRÍTICO: Utilice únicamente las cadenas de identificación del modelo exactas de la tabla anterior; están completas tal como están. No agregue sufijos de fecha. Por ejemplo, useclaude-sonnet-4-5, nuncaclaude-sonnet-4-5-20250514ni ninguna otra variante con sufijo de fecha que pueda recordar de los datos de entrenamiento. Si el usuario solicita un modelo anterior que no está en la tabla (por ejemplo, "opus 4.5", "sonnet 3.7"), leashared/models.mdpara obtener la identificación exacta; no construya uno usted mismo.

Una nota: si alguna de las cadenas de modelo anteriores le parece desconocida, es de esperarse; eso solo significa que se publicaron después del corte de datos de entrenamiento. Tenga la seguridad de que son modelos reales; No nos meteríamos contigo de esa manera.

Búsqueda de capacidad en vivo: La tabla anterior está almacenada en caché. Cuando el usuario pregunta "cuál es la ventana de contexto para X", "X admite visión/pensamiento/esfuerzo" o "qué modelos admiten Y", consulte la API de modelos (client.models.retrieve(id)/client.models.list()); consulteshared/models.mdpara obtener la referencia de campo y ejemplos de filtros de capacidad.

Pensamiento y esfuerzo (referencia rápida)

Opus 4.7 - Solo pensamiento adaptativo: Utilicethinking: {type: "adaptive"}.thinking: {type: "enabled", budget_tokens: N}devuelve un 400 en Opus 4.7; el adaptativo es el único modo activado.{type: "disabled"}y omitirthinkingfuncionan. Los parámetros de muestreo (temperature,top_p,top_k) también se eliminan y serán 400. Consulteshared/model-migration.md-> Migración a Opus 4.7 para obtener la lista completa de cambios importantes. Opus 4.6 - Pensamiento adaptativo (recomendado): Utilicethinking: {type: "adaptive"}. Claude decide dinámicamente cuándo y cuánto pensar. No se necesitabudget_tokens:budget_tokensestá obsoleto en Opus 4.6 y Sonnet 4.6 y no debe usarse para código nuevo. El pensamiento adaptativo también habilita automáticamente el pensamiento entrelazado (no se necesita encabezado beta). Cuando el usuario pide "pensamiento extendido", "presupuesto de pensamiento", obudget_tokens: utilice siempre Opus 4.7 o 4.6 conthinking: {type: "adaptive"}. El concepto de un presupuesto simbólico fijo para el pensamiento está en desuso: el pensamiento adaptativo lo reemplaza. NO usebudget_tokenspara el nuevo código 4.6/4.7 y NO cambie a un modelo anterior. Exclusión de migración gradual:budget_tokensaún funciona en Opus 4.6 y Sonnet 4.6 como una trampilla de escape de transición; si está migrando el código existente y necesita un techo de token rígido antes de ajustareffort, consulteshared/model-migration.md-> Transicional trampilla de escape. Nota: esta exclusión no se aplica a Opus 4.7:budget_tokensse elimina por completo allí. Parámetro de esfuerzo (GA, sin encabezado beta): Controla la profundidad del pensamiento y el gasto general de tokens a través deoutput_config: {effort: "low"|"medium"|"high"|"max"}(dentro deoutput_config, no de nivel superior). El valor predeterminado eshigh(equivale a omitirlo).maxes solo de nivel Opus (Opus 4.6 y posteriores, no Sonnet ni Haiku). Opus 4.7 agrega"xhigh"(entrehighymax): la mejor configuración para la mayoría de los casos de uso de codificación y agentes en 4.7, y la opción predeterminada en Claude Code; utilice un mínimo dehighpara la mayoría de los trabajos sensibles a la inteligencia. Funciona en Opus 4.5, Opus 4.6, Opus 4.7 y Sonnet 4.6. Error en Sonnet 4.5/Haiku 4.5. En Opus 4.7, el esfuerzo importa más que en cualquier Opus anterior: vuelva a sintonizarlo al migrar. Combine con el pensamiento adaptativo para obtener las mejores compensaciones entre costo y calidad. Un menor esfuerzo significa menos llamadas a herramientas y más consolidadas, menos preámbulo y confirmaciones más concisas:highes a menudo el punto ideal para equilibrar la calidad y la eficiencia del token; usemaxcuando la corrección importe más que el costo; utilicelowpara subagentes o tareas simples.

Opus 4.7 - contenido pensado omitido de forma predeterminada: Los bloquesthinkingaún se transmiten pero su texto está vacío a menos que opte por suscribirse conthinking: {type: "adaptive", display: "summarized"}(el valor predeterminado es"omitted"). Cambio silencioso, sin errores. Si transmite el razonamiento a los usuarios, el valor predeterminado parece una pausa larga antes de la salida; configure"summarized"para restaurar el progreso visible.

Presupuestos de tareas (beta, Opus 4.7):output_config: {task_budget: {type: "tokens", total: N}}le dice al modelo cuántos tokens tiene para un ciclo agente completo; ve una cuenta regresiva en ejecución y se automodera (mínimo 20 000; encabezado betatask-budgets-2026-03-13). A diferencia demax_tokens, que es un límite máximo por respuesta obligatorio que el modelo desconoce. Vershared/model-migration.md-> Presupuestos de tareas.

Soneto 4.6: Admite el pensamiento adaptativo (thinking: {type: "adaptive"}).budget_tokensestá obsoleto en Sonnet 4.6; en su lugar, utilice el pensamiento adaptativo.

Modelos más antiguos (solo si se solicita explícitamente): Si el usuario solicita específicamente Sonnet 4.5 u otro modelo más antiguo, usethinking: {type: "enabled", budget_tokens: N}.budget_tokensdebe ser menor quemax_tokens(mínimo 1024). Nunca elijas un modelo antiguo sólo porque el usuario mencionabudget_tokens; en su lugar, usa Opus 4.7 con pensamiento adaptativo.

Compactación (Referencia rápida)

Beta, Opus 4.7, Opus 4.6 y Sonnet 4.6. Para conversaciones de larga duración que pueden exceder la ventana de contexto de 1 M, habilite la compactación del lado del servidor. La API resume automáticamente el contexto anterior cuando se acerca al umbral de activación (predeterminado: 150 000 tokens). Requiere el encabezado betacompact-2026-01-12.

Crítico: Añaderesponse.content(no solo el texto) a tus mensajes en cada turno. Los bloques de compactación en la respuesta deben conservarse: la API los usa para reemplazar el historial compactado en la siguiente solicitud. Extraer solo la cadena de texto y agregarla perderá silenciosamente el estado de compactación.

Consulte{lang}/claude-api/README.md(sección Compactación) para ver ejemplos de código. Documentos completos a través de WebFetch enshared/live-sources.md.

Almacenamiento en caché rápido (referencia rápida)

Coincidencia de prefijo. Cualquier cambio de byte en cualquier parte del prefijo invalida todo lo que sigue. El orden de renderizado estools->system->messages. Mantenga primero el contenido estable (mensaje del sistema congelado, lista de herramientas determinista), coloque contenido volátil (marcas de tiempo, ID por solicitud, preguntas variables) después del último punto de interrupcióncache_control.

El almacenamiento en caché automático de nivel superior (cache_control: {type: "ephemeral"}enmessages.create()) es la opción más sencilla cuando no necesitas una ubicación detallada. Máximo 4 puntos de interrupción por solicitud. El prefijo mínimo que se puede almacenar en caché es ~1024 tokens; los prefijos más cortos no se almacenarán en caché de forma silenciosa.

Verifique conusage.cache_read_input_tokens: si es cero en solicitudes repetidas, hay un invalidador silencioso en funcionamiento (datetime.now()en el indicador del sistema, JSON sin clasificar, conjunto de herramientas variable).

Para patrones de ubicación, orientación arquitectónica y la lista de verificación de auditoría del validador silencioso: leashared/prompt-caching.md. Sintaxis específica del idioma:{lang}/claude-api/README.md(sección Almacenamiento en caché de avisos).

Agentes administrados (Beta)

Agentes administrados es una tercera superficie: agentes con estado administrados por el servidor con ejecución de herramientas alojadas en Anthropic. Usted crea una configuración de agente versionada y persistente (POST /v1/agents) y luego inicia sesiones que hacen referencia a ella. Cada sesión proporciona un contenedor como espacio de trabajo del agente: allí se ejecutan bash, operaciones de archivos y ejecución de código; el bucle del agente se ejecuta en la capa de orquestación de Anthropic y actúa sobre el contenedor a través de herramientas. La sesión transmite eventos; usted envía mensajes y resultados de herramientas.

Los agentes administrados son solo propios. No está disponible en Amazon Bedrock, Google Vertex AI ni Microsoft Foundry. Para agentes de proveedores externos, utilice el uso de la herramienta Claude API +.

Flujo obligatorio: Agente (una vez) -> Sesión (cada ejecución).model/system/toolsviven en el agente, nunca en la sesión. Consulteshared/managed-agents-overview.mdpara obtener la guía de lectura completa, los encabezados beta y los errores.

Encabezados beta:managed-agents-2026-04-01: el SDK configura esto automáticamente para todas las llamadasclient.beta.{agents,environments,sessions,vaults,memory_stores}.*. La API de habilidades usaskills-2025-10-02y la API de archivos usafiles-api-2025-04-14, pero no es necesario pasarlas explícitamente para puntos finales que no sean/v1/skillsy/v1/files.

Subcomandos - invocar directamente con/claude-api <subcommand>:

Guía de lectura: Comience conshared/managed-agents-overview.md, luego los archivos actualesshared/managed-agents-*.md(núcleo, entornos, herramientas, eventos, resultados, multiagente, webhooks, memoria, patrones de cliente, incorporación, referencia de API). Para Python, TypeScript, Go, Ruby, PHP y Java, lea{lang}/managed-agents/README.mdpara ver ejemplos de código. Para cURL, leacurl/managed-agents.md. Los agentes son persistentes: se crean una vez, se hace referencia por ID. Almacene el ID del agente devuelto poragents.createy páselo a cadasessions.createposterior; no llame aagents.createen la ruta de solicitud. La CLI de Anthropic es una forma conveniente de crear agentes y entornos desde YAML con versión controlada (URL enshared/live-sources.md). Si un enlace que necesita no se muestra en el idioma README, WebObtenga la entrada relevante deshared/live-sources.mden lugar de adivinar. Actualmente, C# no admite agentes administrados; utilice HTTP sin formato decurl/managed-agents.mdcomo referencia.

Cuando el usuario desea configurar un agente administrado desde cero (por ejemplo, "cómo empiezo", "guíame en la creación de uno", "configurar un nuevo agente"): leashared/managed-agents-onboarding.mdy ejecute su entrevista; el mismo flujo que el subcomandomanaged-agents-onboard.

Cuando el usuario pregunta "¿cómo escribo el código de cliente para X": llegar ashared/managed-agents-client-patterns.md: cubre la reconexión de flujo sin pérdidas, la puerta en cola/procesada deprocessed_at, la interrupción, el viaje de ida y vuelta detool_confirmation, la puerta de interrupción inactiva/terminada correcta, la carrera de estado posterior a la inactividad, el orden de la transmisión primero, los errores de montaje de archivos, el mantenimiento de las credenciales del lado del host mediante herramientas personalizadas, etc.

Guía de lectura

Después de detectar el idioma, lea los archivos relevantes según las necesidades del usuario:

Referencia rápida de tareas

Clasificación de texto único/resumen/extracción/Preguntas y respuestas: -> Sólo lectura{lang}/claude-api/README.md

UI de chat o visualización de respuesta en tiempo real: -> Leer{lang}/claude-api/README.md+{lang}/claude-api/streaming.md

Conversaciones de larga duración (pueden exceder la ventana de contexto): -> Leer{lang}/claude-api/README.md- ver sección Compactación Migrar a un modelo más nuevo (Opus 4.7 / Opus 4.6 / Sonnet 4.6) o reemplazar un modelo retirado: -> Leershared/model-migration.md Avisar almacenamiento en caché/optimizar el almacenamiento en caché/ "¿por qué mi tasa de aciertos en caché es baja?": -> Leershared/prompt-caching.md+{lang}/claude-api/README.md(sección de almacenamiento en caché de avisos)

Llamadas a funciones/uso de herramientas/agentes: -> Leer{lang}/claude-api/README.md+shared/tool-use-concepts.md+{lang}/claude-api/tool-use.md

Diseño del agente (superficie de herramientas, gestión de contexto, estrategia de almacenamiento en caché): -> Leershared/agent-design.md

Procesamiento por lotes (no sensible a la latencia): -> Leer{lang}/claude-api/README.md+{lang}/claude-api/batches.md

Cargas de archivos en múltiples solicitudes: -> Leer{lang}/claude-api/README.md+{lang}/claude-api/files-api.md

Agentes administrados (agentes con estado administrados por el servidor con espacio de trabajo): -> Leershared/managed-agents-overview.md+ el resto de archivosshared/managed-agents-*.md. Para Python, TypeScript, Go, Ruby, PHP y Java, lea{lang}/managed-agents/README.mdpara ver ejemplos de código. Para cURL, leacurl/managed-agents.md. Los agentes son persistentes: se crean una vez, se hace referencia por ID. Almacene el ID del agente devuelto poragents.createy páselo a cadasessions.createposterior; no llame aagents.createen la ruta de solicitud. La CLI de Anthropic es una forma conveniente de crear agentes y entornos desde YAML con versión controlada (URL enshared/live-sources.md). Si un enlace que necesita no se muestra en el idioma README, WebObtenga la entrada relevante deshared/live-sources.mden lugar de adivinar. Actualmente, C# no admite agentes administrados; utilice HTTP sin formato decurl/managed-agents.mdcomo referencia.

Claude API (referencia completa del archivo)

Lea la carpeta Claude API específica del idioma ({language}/claude-api/):

1. {language}/claude-api/README.md - Lea esto primero. Instalación, inicio rápido, patrones comunes, manejo de errores.
2. shared/tool-use-concepts.md: lee cuando el usuario necesita llamadas a funciones, ejecución de código, memoria o salidas estructuradas. Abarca fundamentos conceptuales.
3. shared/agent-design.md - Lea al diseñar un agente: bash frente a herramientas dedicadas, llamada de herramientas programáticas, búsqueda/habilidades de herramientas, edición de contexto frente a compactación frente a memoria, principios de almacenamiento en caché.
4. {language}/claude-api/tool-use.md: lectura de ejemplos de código de uso de herramientas específicas del lenguaje (ejecutor de herramientas, bucle manual, ejecución de código, memoria, salidas estructuradas).
5. {language}/claude-api/streaming.md: lea al crear interfaces de usuario o interfaces de chat que muestren respuestas de forma incremental.
6. {language}/claude-api/batches.md: lectura cuando se procesan muchas solicitudes sin conexión (no sensible a la latencia). Se ejecuta de forma asincrónica al 50% del costo.
7. {language}/claude-api/files-api.md: lectura cuando se envía el mismo archivo en varias solicitudes sin volver a cargarlo.
8. shared/prompt-caching.md: lectura al agregar u optimizar el almacenamiento en caché de mensajes. Cubre el diseño de estabilidad de prefijos, la ubicación de puntos de interrupción y antipatrones que invalidan silenciosamente el caché.
9. shared/error-codes.md: lectura al depurar errores HTTP o implementar el manejo de errores.
10. shared/model-migration.md: lea cuando actualice a modelos más nuevos, reemplace modelos retirados o traduzca patronesbudget_tokens/prellenado a la API actual.
11. shared/live-sources.md: URL de WebFetch para obtener la documentación oficial más reciente.

Cuándo utilizar WebFetch

Utilice WebFetch para obtener la documentación más reciente cuando:

• El usuario solicita información "más reciente" o "actual"
• Los datos almacenados en caché parecen incorrectos
• El usuario pregunta sobre funciones que no se tratan aquí

Las URL de documentación en vivo están enshared/live-sources.md.

Errores comunes

• No trunca las entradas al pasar archivos o contenido a la API. Si el contenido es demasiado largo para caber en la ventana contextual, notifique al usuario y analice las opciones (fragmentación, resumen, etc.) en lugar de truncarlo silenciosamente.
• Pensamiento Opus 4.7: Solo adaptativo.thinking: {type: "enabled", budget_tokens: N}devuelve 400 en Opus 4.7;budget_tokensse elimina por completo allí (junto contemperature,top_p,top_k). Utilicethinking: {type: "adaptive"}.
• Pensamiento de Opus 4.6 / Sonnet 4.6: Usethinking: {type: "adaptive"}- NO usebudget_tokenspara el nuevo código 4.6 (obsoleto tanto en Opus 4.6 como en Sonnet 4.6; para la migración gradual del código existente, consulte la trampilla de escape de transición enshared/model-migration.md; tenga en cuenta que esta exclusión no se aplica a Opus 4.7). Para modelos más antiguos,budget_tokensdebe ser menor quemax_tokens(mínimo 1024). Esto generará un error si lo hace mal.
• Se eliminó el precargado de la familia 4.6/4.7: Los precargados de mensajes del asistente (precargados del último turno del asistente) devuelven un error 400 en Opus 4.6, Opus 4.7 y Sonnet 4.6. Utilice salidas estructuradas (output_config.format) o instrucciones de aviso del sistema para controlar el formato de respuesta.
• Confirme el alcance de la migración antes de editar: Cuando un usuario solicita migrar código a un modelo Claude más nuevo sin nombrar un archivo, directorio o lista de archivos específicos, pregunte qué alcance aplicar primero: el directorio de trabajo completo, un subdirectorio específico o un conjunto específico de archivos. No comience a editar hasta que el usuario lo confirme. Frases imperativas como "migrar mi código base", "mover mi proyecto a X", "actualizar a Sonnet 4.6" o "migrar a Opus 4.7" son todavía ambiguas: te dicen qué hacer pero no dónde, así que pregunta. Continúe sin preguntar solo cuando el mensaje nombre un archivo exacto, un directorio específico o una lista de archivos explícita ("migrarapp.py", "migrar todo bajoservices/", "actualizara.pyyb.py"). Consulteshared/model-migration.mdPaso 0.
• Valores predeterminados demax_tokens: No subestimesmax_tokens: presionar el límite trunca la salida a mitad del pensamiento y requiere un nuevo intento. Para solicitudes que no son de transmisión, el valor predeterminado es~16000(mantiene las respuestas dentro de los tiempos de espera HTTP del SDK). Para solicitudes de transmisión, use de forma predeterminada~64000(los tiempos de espera no son una preocupación, así que déle espacio al modelo). Solo baje cuando tenga una razón importante: clasificación (~256), límites de costos o resultados deliberadamente cortos.
• Tokens de salida de 128K: Opus 4.6 y Opus 4.7 admiten hasta 128Kmax_tokens, pero los SDK requieren transmisión para valores tan grandes para evitar tiempos de espera de HTTP. Utilice.stream()con.get_final_message()/.finalMessage().
• Análisis JSON de llamada de herramienta (familia 4.6/4.7): Opus 4.6, Opus 4.7 y Sonnet 4.6 pueden producir diferentes escapes de cadenas JSON en los campos de llamada de herramientainput(por ejemplo, Unicode o escape de barra diagonal). Analice siempre las entradas de la herramienta conjson.loads()/JSON.parse(); nunca haga coincidencias de cadenas sin formato en la entrada serializada.
• Salidas estructuradas (todos los modelos): Utiliceoutput_config: {format: {...}}en lugar del parámetro obsoletooutput_formatenmessages.create(). Este es un cambio de API general, no específico de 4.6.
• No vuelva a implementar la funcionalidad del SDK: El SDK proporciona ayudas de alto nivel; utilícelas en lugar de compilarlas desde cero. Específicamente: usestream.finalMessage()en lugar de empaquetar eventos.on()ennew Promise(); utilice clases de excepción escritas (Anthropic.RateLimitError, etc.) en lugar de mensajes de error de coincidencia de cadenas; utilice tipos de SDK (Anthropic.MessageParam,Anthropic.Tool,Anthropic.Message, etc.) en lugar de redefinir interfaces equivalentes.
• No defina tipos personalizados para estructuras de datos del SDK: El SDK exporta tipos para todos los objetos API. UtiliceAnthropic.MessageParampara mensajes,Anthropic.Toolpara definiciones de herramientas,Anthropic.ToolUseBlock/Anthropic.ToolResultBlockParampara resultados de herramientas,Anthropic.Messagepara respuestas. Definir su propiointerface ChatMessage { role: string; content: unknown }duplica lo que el SDK ya proporciona y pierde seguridad de tipos.
• Salida de informes y documentos: Para tareas que generan informes, documentos o visualizaciones, el entorno limitado de ejecución de código tienepython-docx,python-pptx,matplotlib,pillowypypdfpreinstalados. Claude puede generar archivos formateados (DOCX, PDF, gráficos) y devolverlos a través de la API de archivos; considere esto para solicitudes de tipo "informe" o "documento" en lugar de texto estándar sin formato.

Archivos de recursos

LICENCIA.txt

Descargar LICENCIA.txt

Recurso binario

csharp/claude-api.md

Descargar csharp/claude-api.md

Recurso binario

curl/ejemplos.md

Descargar curl/examples.md

Recurso binario

curl/agentes-administrados.md

Descargar curl/managed-agents.md

Recurso binario

ir/claude-api.md

Descargar go/claude-api.md

Recurso binario

ir/agentes-administrados/README.md

Descargar go/managed-agents/README.md

Recurso binario

java/claude-api.md

Descargar java/claude-api.md

Recurso binario

java/agentes-administrados/README.md

Descargar java/managed-agents/README.md

Recurso binario

php/claude-api.md

Descargar php/claude-api.md

Recurso binario

php/agentes-administrados/README.md

Descargar php/managed-agents/README.md

Recurso binario

Python/claude-api/README.md

Descargar python/claude-api/README.md

Recurso binario

Python/claude-api/batches.md

Descargar python/claude-api/batches.md

# Message Batches API — Python

The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.

## Key Facts

- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)

---

## Create a Batch

```python
importar antrópico
desde anthropic.types.message_create_params importar MessageCreateParamsNonStreaming
de anthropic.types.messages.batch_create_params solicitud de importación

cliente = antrópico.Antrópico()

message_batch = cliente.messages.batches.create(
    solicitudes=[
        Solicitud(
            custom_id="solicitud-1",
            params=MensajeCreateParamsNonStreaming(
                modelo="claude-opus-4-7",
                tokens_max=16000,
                mensajes=[{"role": "usuario", "contenido": "Resumir los impactos del cambio climático"}]
            )
        ),
        Solicitud(
            custom_id="solicitud-2",
            params=MensajeCreateParamsNonStreaming(
                modelo="claude-opus-4-7",
                tokens_max=16000,
                mensajes=[{"role": "usuario", "contenido": "Explicar los conceptos básicos de la computación cuántica"}]
            )
        ),
    ]
)

print(f"ID de lote: {message_batch.id}")
imprimir(f"Estado: {message_batch.processing_status}")

Poll for Completion

tiempo de importación

mientras que Verdadero:
    lote = cliente.messages.batches.retrieve(message_batch.id)
    si lote.processing_status == "finalizado":
        romper
    print(f"Estado: {batch.processing_status}, procesando: {batch.request_counts.processing}")
    tiempo.dormir(60)

print("¡Lote completo!")
print(f"Exitoso: {batch.request_counts.succeeded}")
imprimir(f"Error: {batch.request_counts.errored}")

Retrieve Results

para obtener el resultado en client.messages.batches.results(message_batch.id):
    coincidir resultado.resultado.tipo:
        caso "tuvo éxito":
            mensaje = resultado.resultado.mensaje
            texto = siguiente((b.texto para b en msg.content si b.tipo == "texto"), "")
            imprimir(f"[{result.custom_id}] {texto[:100]}")
        caso "error":
            si resultado.resultado.error.tipo == "request_invalid":
                print(f"[{result.custom_id}] Error de validación: corregir la solicitud y volver a intentarlo")
            más:
                print(f"[{result.custom_id}] Error del servidor: es seguro volver a intentarlo")
        caso "cancelado":
            print(f"[{result.custom_id}] Cancelado")
        caso "caducado":
            print(f"[{result.custom_id}] Caducado - reenviar")

Cancel a Batch

cancelado = client.messages.batches.cancel(message_batch.id)
print(f"Estado: {cancelled.processing_status}") # "cancelando"

Batch with Prompt Caching

sistema_compartido = [
    {"type": "text", "text": "Eres analista literario."},
    {
        "tipo": "texto",
        "texto": texto_documento_grande, # Compartido en todas las solicitudes
        "cache_control": {"tipo": "efímero"}
    }
]

message_batch = cliente.messages.batches.create(
    solicitudes=[
        Solicitud(
            custom_id=f"análisis-{i}",
            params=MensajeCreateParamsNonStreaming(
                modelo="claude-opus-4-7",
                tokens_max=16000,
                sistema = sistema_compartido,
                mensajes=[{"rol": "usuario", "contenido": pregunta}]
            )
        )
        para i, pregunta en enumerar (preguntas)
    ]
)

Full End-to-End Example

importar antrópico
tiempo de importación
desde anthropic.types.message_create_params importar MessageCreateParamsNonStreaming
de anthropic.types.messages.batch_create_params solicitud de importación

cliente = antrópico.Antrópico()

# 1. Preparar solicitudes
artículos_a_clasificar = [
    "¡La calidad del producto es excelente!",
    "Pésimo servicio al cliente, nunca más.",
    "Está bien, nada especial.",
]

solicitudes = [
    Solicitud(
        custom_id=f"clasificar-{i}",
        params=MensajeCreateParamsNonStreaming(
            modelo="claude-haiku-4-5",
            tokens_max=50,
            mensajes=[{
                "rol": "usuario",
                "content": f"Clasificar como positivo/negativo/neutral (una palabra): {text}"
            }]
        )
    )
    para i, texto en enumerar (items_to_classify)
]

# 2. Crear lote
lote = cliente.mensajes.lotes.create(solicitudes=solicitudes)
print(f"Lote creado: {batch.id}")

# 3. Espere a que finalice
mientras que Verdadero:
    lote = cliente.mensajes.lotes.retrieve(lote.id)
    si lote.processing_status == "finalizado":
        romper
    tiempo.dormir(10)

# 4. Recopilar resultados
resultados = {}
para obtener el resultado en client.messages.batches.results(batch.id):
    si result.result.type == "tuvo éxito":
        mensaje = resultado.resultado.mensaje
        resultados[resultado.custom_id] = siguiente((b.texto para b en msg.content si b.tipo == "texto"), "")

para custom_id, clasificación en ordenados(resultados.items()):
    imprimir(f"{custom_id}: {classification}")

### python/claude-api/archivos-api.md

[Descargar python/claude-api/files-api.md](/skills/claude-api/python/claude-api/files-api.md)

```markdown
# Files API — Python

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

## Key Facts

- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI

---

## Upload a File

```python
importar antrópico

cliente = antrópico.Antrópico()

subido = cliente.beta.files.upload(
    archivo=("informe.pdf", abrir("informe.pdf", "rb"), "aplicación/pdf"),
)
print(f"ID de archivo: {uploaded.id}")
print(f"Tamaño: {uploaded.size_bytes} bytes")

Use a File in Messages

PDF / Text Document

respuesta = cliente.beta.mensajes.create(
    modelo="claude-opus-4-7",
    tokens_max=16000,
    mensajes=[{
        "rol": "usuario",
        "contenido": [
            {"type": "text", "text": "Resumir los hallazgos clave de este informe."},
            {
                "tipo": "documento",
                "fuente": {"tipo": "archivo", "file_id": subido.id},
                "title": "Informe del cuarto trimestre", # opcional
                "citations": {"enabled": True} # opcional, habilita las citas
            }
        ]
    }],
    betas=["archivos-api-2025-04-14"],
)
para bloquear en respuesta.contenido:
    si bloque.tipo == "texto":
        imprimir (bloque.texto)

Image

archivo_imagen = cliente.beta.files.upload(
    archivo=("foto.png", abrir("foto.png", "rb"), "imagen/png"),
)

respuesta = cliente.beta.mensajes.create(
    modelo="claude-opus-4-7",
    tokens_max=16000,
    mensajes=[{
        "rol": "usuario",
        "contenido": [
            {"type": "text", "text": "¿Qué hay en esta imagen?"},
            {
                "tipo": "imagen",
                "fuente": {"tipo": "archivo", "archivo_id": archivo_imagen.id}
            }
        ]
    }],
    betas=["archivos-api-2025-04-14"],
)

Manage Files

List Files

archivos = cliente.beta.archivos.lista()
para f en archivos.datos:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

Get File Metadata

file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Nombre de archivo: {file_info.filename}")
print(f"Tipo MIME: {file_info.mime_type}")

Delete a File

cliente.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

Download a File

Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("salida.txt")

Full End-to-End Example

Upload a document once, ask multiple questions about it:

importar antrópico

cliente = antrópico.Antrópico()

# 1. Sube una vez
subido = cliente.beta.files.upload(
    archivo=("contrato.pdf", open("contrato.pdf", "rb"), "aplicación/pdf"),
)
print(f"Subido: {uploaded.id}")

# 2. Haga varias preguntas usando el mismo file_id
preguntas = [
    "¿Cuáles son los términos y condiciones clave?",
    "¿Qué es la cláusula de rescisión?",
    "Resumir el cronograma de pagos.",
]

para preguntas en preguntas:
    respuesta = cliente.beta.mensajes.create(
        modelo="claude-opus-4-7",
        tokens_max=16000,
        mensajes=[{
            "rol": "usuario",
            "contenido": [
                {"tipo": "texto", "texto": pregunta},
                {
                    "tipo": "documento",
                    "fuente": {"tipo": "archivo", "file_id": subido.id}
                }
            ]
        }],
        betas=["archivos-api-2025-04-14"],
    )
    imprimir(f"\nQ: {question}")
    texto = siguiente((b.texto para b en respuesta.contenido si b.tipo == "texto"), "")
    imprimir(f"A: {texto[:200]}")

# 3. Limpiar cuando haya terminado
client.beta.files.delete(cargado.id)

### Python/claude-api/streaming.md

[Descargar python/claude-api/streaming.md](/skills/claude-api/python/claude-api/streaming.md)

```markdown
# Streaming — Python

## Quick Start

```python
con client.messages.stream(
    modelo="claude-opus-4-7",
    tokens_max=64000,
    mensajes=[{"rol": "usuario", "contenido": "Escribe una historia"}]
) como flujo:
    para texto en stream.text_stream:
        imprimir(texto, fin="", vaciar=Verdadero)

Async

asíncrono con async_client.messages.stream(
    modelo="claude-opus-4-7",
    tokens_max=64000,
    mensajes=[{"rol": "usuario", "contenido": "Escribe una historia"}]
) como flujo:
    asíncrono para texto en stream.text_stream:
        imprimir(texto, fin="", vaciar=Verdadero)

Handling Different Content Types

Claude may return text, thinking blocks, or tool use. Handle each appropriately:

con client.messages.stream(
    modelo="claude-opus-4-7",
    tokens_max=64000,
    pensando = {"tipo": "adaptativo"},
    mensajes=[{"role": "usuario", "content": "Analizar este problema"}]
) como flujo:
    para evento en flujo:
        si event.type == "content_block_start":
            if event.content_block.type == "pensando":
                imprimir("\n[Pensando...]")
            elif event.content_block.type == "texto":
                imprimir("\n[Respuesta:]")

        elif event.type == "content_block_delta":
            si event.delta.type == "pensando_delta":
                print(event.delta.thinking, end="", rubor=Verdadero)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", rubor=Verdadero)

Streaming with Tool Use

The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:

con client.messages.stream(
    modelo="claude-opus-4-7",
    tokens_max=64000,
    herramientas = herramientas,
    mensajes=mensajes
) como flujo:
    para texto en stream.text_stream:
        imprimir(texto, fin="", vaciar=Verdadero)

    respuesta = flujo.get_final_message()
    # Continuar con la ejecución de la herramienta si respuesta.stop_reason == "tool_use"

Getting the Final Message

con client.messages.stream(
    modelo="claude-opus-4-7",
    tokens_max=64000,
    mensajes=[{"rol": "usuario", "contenido": "Hola"}]
) como flujo:
    para texto en stream.text_stream:
        imprimir(texto, fin="", vaciar=Verdadero)

    # Recibir el mensaje completo después de la transmisión
    mensaje_final = flujo.get_message_final()
    print(f"\n\nTokens utilizados: {final_message.usage.output_tokens}")

Streaming with Progress Updates

def stream_with_progress(cliente, **kwargs):
    """Transmitir una respuesta con actualizaciones de progreso."""
    tokens_total = 0
    contenido_partes = []

    con client.messages.stream(**kwargs) como flujo:
        para evento en flujo:
            si event.type == "content_block_delta":
                si event.delta.type == "text_delta":
                    texto = evento.delta.texto
                    content_parts.append(texto)
                    imprimir(texto, fin="", vaciar=Verdadero)

            elif event.type == "mensaje_delta":
                si event.usage y event.usage.output_tokens no son Ninguno:
                    total_tokens = evento.uso.output_tokens

        mensaje_final = flujo.get_message_final()

    print(f"\n\n[Tokens utilizados: {total_tokens}]")
    devolver "".join(content_parts)

Error Handling in Streams

prueba:
    con client.messages.stream(
        modelo="claude-opus-4-7",
        tokens_max=64000,
        mensajes=[{"rol": "usuario", "contenido": "Escribe una historia"}]
    ) como flujo:
        para texto en stream.text_stream:
            imprimir(texto, fin="", vaciar=Verdadero)
excepto antrópico.APIConnectionError:
    print("\nConexión perdida. Vuelva a intentarlo.")
excepto antrópico.RateLimitError:
    print("\nTarifa limitada. Espere y vuelva a intentarlo.")
excepto anthropic.APIStatusError como e:
    print(f"\nError de API: {e.status_code}")

Stream Event Types

Best Practices

1. Always flush output — Use flush=True to show tokens immediately
2. Handle partial responses — If the stream is interrupted, you may have incomplete content
3. Track token usage — The message_delta event contains usage information
4. Use timeouts — Set appropriate timeouts for your application
5. Default to streaming — Use .get_final_message() to get the complete response even when streaming, giving you timeout protection without needing to handle individual events

### python/claude-api/tool-use.md

[Descargar python/claude-api/tool-use.md](/skills/claude-api/python/claude-api/tool-use.md)

_Recurso binario_

### python/agentes-administrados/README.md

[Descargar python/managed-agents/README.md](/skills/claude-api/python/managed-agents/README.md)

_Recurso binario_

### rubí/claude-api.md

[Descargar ruby/claude-api.md](/skills/claude-api/ruby/claude-api.md)

```markdown
# Claude API — Ruby

> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.

## Installation

```bash
instalación de gemas antrópicas

Client Initialization

requieren "antrópico"

# Predeterminado (usa ANTHROPIC_API_KEY env var)
cliente = Antrópico::Cliente.nuevo

# Clave API explícita
cliente = Anthropic::Client.new(api_key: "tu-clave-api")

Basic Message Request

mensaje = cliente.mensajes.create(
  modelo::"claude-opus-4-7",
  tokens_max: 16000,
  mensajes: [
    { rol: "usuario", contenido: "¿Cuál es la capital de Francia?" }
  ]
)
# El contenido es una matriz de objetos de bloques polimórficos (TextBlock, ThinkingBlock,
# BloqueUsoHerramienta,...)..type es un símbolo; compárelo con:text, no con "texto".
# .text genera NoMethodError en entradas que no son TextBlock.
message.content.each hacer |bloquear|
  pone bloque.texto si bloque.tipo ==:texto
fin

Streaming

flujo = cliente.mensajes.flujo(
  modelo::"claude-opus-4-7",
  tokens_max: 64000,
  mensajes: [{ rol: "usuario", contenido: "Escribir un haiku" }]
)

flujo.texto.cada uno { |texto| imprimir (texto) }

Tool Use

The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.

Tool Runner (Beta)

clase GetWeatherInput < Antrópico::ModeloBase
  requerido:ubicación, Cadena, doc: "Ciudad y estado, por ejemplo, San Francisco, CA"
fin

clase GetWeather < Antrópico::BaseTool
  doc "Obtener el clima actual para una ubicación"

  input_schema ObtenerWeatherInput

  llamada definida (entrada)
    "El clima en #{input.location} es soleado y 72°F".
  fin
fin

cliente.beta.messages.tool_runner(
  modelo::"claude-opus-4-7",
  tokens_max: 16000,
  herramientas: [GetWeather.new],
  mensajes: [{ rol: "usuario", contenido: "¿Cuál es el clima en San Francisco?" }]
).each_message hacer |mensaje|
  pone mensaje.contenido
fin

Manual Loop

See the shared tool use concepts for the tool definition format and agentic loop pattern.

Prompt Caching

system_: (trailing underscore — avoids shadowing Kernel#system) takes an array of text blocks; set cache_control on the last block. Plain hashes work via the OrHash type alias. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.

mensaje = cliente.mensajes.create(
  modelo::"claude-opus-4-7",
  tokens_max: 16000,
  sistema_: [
    { tipo: "texto", texto: long_system_prompt, cache_control: { tipo: "efímero" } }
  ],
  mensajes: [{ rol: "usuario", contenido: "Resumir los puntos clave" }]
)

For 1-hour TTL: cache_control: { type: "ephemeral", ttl: "1h" }. There's also a top-level cache_control: on messages.create that auto-places on the last cacheable block.

Verify hits via message.usage.cache_creation_input_tokens / message.usage.cache_read_input_tokens.

### ruby/agentes-administrados/README.md

[Descargar ruby/managed-agents/README.md](/skills/claude-api/ruby/managed-agents/README.md)

_Recurso binario_

### compartido/diseño-agente.md

[Descargar compartido/agent-design.md](/skills/claude-api/shared/agent-design.md)

_Recurso binario_

### compartido/códigos de error.md

[Descargar compartido/códigos de error.md](/skills/claude-api/shared/códigos de error.md)

_Recurso binario_

### compartido/live-sources.md

[Descargar compartido/live-sources.md](/skills/claude-api/shared/live-sources.md)

_Recurso binario_

### agentes-api-reference.md compartidos/administrados

[Descargar Shared/Managed-Agents-api-reference.md](/skills/claude-api/shared/managed-agents-api-reference.md)

_Recurso binario_

### patrones-cliente-agentes-administrados/compartidos.md

[Descargar shared/managed-agents-client-patterns.md](/skills/claude-api/shared/managed-agents-client-patterns.md)

_Recurso binario_

### agentes-core.md compartidos/administrados

[Descargar shared/managed-agents-core.md](/skills/claude-api/shared/managed-agents-core.md)

_Recurso binario_

### entornos-de-agentes-compartidos/administrados.md

[Descargar entornos-de-agentes-administrados/compartidos.md](/skills/claude-api/shared/managed-agents-environments.md)

_Recurso binario_

### eventos-agentes-compartidos/administrados.md

[Descargar shared/managed-agents-events.md](/skills/claude-api/shared/managed-agents-events.md)

_Recurso binario_

### memoria-de-agentes-compartida/administrada.md

[Descargar shared/managed-agents-memory.md](/skills/claude-api/shared/managed-agents-memory.md)

_Recurso binario_

### agentes-compartidos/administrados-multiagent.md

[Descargar Shared/Managed-Agents-Multiagent.md](/skills/claude-api/shared/Managed-Agents-Multiagent.md)

_Recurso binario_

### onboarding-de-agentes-compartidos/administrados.md

[Descargar shared/managed-agents-onboarding.md](/skills/claude-api/shared/managed-agents-onboarding.md)

_Recurso binario_

### resultados-agentes-compartidos/administrados.md

[Descargar compartido/managed-agents-outcomes.md](/skills/claude-api/shared/managed-agents-outcomes.md)

_Recurso binario_

### descripción general de agentes compartidos/administrados.md

[Descargar shared/managed-agents-overview.md](/skills/claude-api/shared/managed-agents-overview.md)

_Recurso binario_

### herramientas-agentes-administrados/compartidos.md

[Descargar shared/managed-agents-tools.md](/skills/claude-api/shared/managed-agents-tools.md)

_Recurso binario_

### agentes-webhooks.md compartidos/administrados

[Descargar shared/managed-agents-webhooks.md](/skills/claude-api/shared/managed-agents-webhooks.md)

```markdown
# Managed Agents — Webhooks

Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.

> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.

---

## Register an endpoint (Console only)

Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.

| Field | Constraint |
|---|---|
| URL | HTTPS on port 443, publicly resolvable hostname |
| Event types | Subscribe per `data.type` — you only receive subscribed types (plus test events) |
| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |

---

## Verify the signature

Every delivery is HMAC-signed. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`.

```python
importar antrópico
desde matraz importar matraz, solicitar

cliente = anthropic.Anthropic() # lee ANTHROPIC_WEBHOOK_SIGNING_KEY del entorno
aplicación = Frasco (__nombre__)


@app.route("/webhook", métodos=["POST"])
def webhook():
    prueba:
        evento = cliente.beta.webhooks.unwrap(
            request.get_data(as_text=Verdadero),
            encabezados = dict (solicitud.encabezados),
        )
    excepto Excepción:
        devolver "firma no válida", 400

    si event.id en visto_event_ids: # reintentos de deduplicación: la identificación es por evento, no por entrega
        devolver "", 204
    visto_event_ids.add(event.id)

    coincidir con evento.tipo.datos:
        caso "session.status_idled":
            sesión = cliente.beta.sesiones.retrieve(evento.datos.id)
            notificar_usuario(sesión)
        caso "vault_credential.refresh_failed":
            alert_oncall(evento.datos.id)

    devolver "", 204

Pass the raw request body to unwrap() — frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.

Payload envelope

{
  "tipo": "evento",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "datos": {
    "tipo": "sesión.status_idled",
    "id": "session_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the state transition happened, not when the webhook fired.

Supported data.type values

Delivery behavior & pitfalls

• No ordering guarantee. session.status_idled may arrive before session.outcome_evaluation_ended even if the evaluation finished first. Sort by envelope created_at if order matters.
• Retries carry the same event.id. At least one retry on non-2xx. Dedupe on event.id.
• 3xx is failure. Redirects are not followed — update the URL in Console if your endpoint moves.
• Auto-disable after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
• Thin payload is intentional. Don't expect stop_reason, outcome_evaluations, credential secrets, etc. on the webhook body — fetch the resource.

### compartido/model-migration.md

[Descargar compartido/model-migration.md](/skills/claude-api/shared/model-migration.md)

_Recurso binario_

### compartido/modelos.md

[Descargar compartido/models.md](/skills/claude-api/shared/models.md)

_Recurso binario_

### compartido/prompt-caching.md

[Descargar compartido/prompt-caching.md](/skills/claude-api/shared/prompt-caching.md)

_Recurso binario_

### compartido/conceptos-de-uso-de-herramientas.md

[Descargar compartido/tool-use-concepts.md](/skills/claude-api/shared/tool-use-concepts.md)

_Recurso binario_

### mecanografiado/claude-api/README.md

[Descargar mecanografiado/claude-api/README.md](/skills/claude-api/typescript/claude-api/README.md)

_Recurso binario_

### mecanografiado/claude-api/batches.md

[Descargar mecanografiado/claude-api/batches.md](/skills/claude-api/typescript/claude-api/batches.md)

```markdown
# Message Batches API — TypeScript

The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.

## Key Facts

- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)

---

## Create a Batch

```typescript
importar Anthropic desde "@anthropic-ai/sdk";

cliente constante = nuevo Antrópico();

const messageBatch = espera client.messages.batches.create({
  solicitudes: [
    {
      custom_id: "solicitud-1",
      parámetros: {
        modelo: "claude-opus-4-7",
        tokens_max: 16000,
        mensajes: [
          { rol: "usuario", contenido: "Resumir los impactos del cambio climático" },
        ],
      },
    },
    {
      custom_id: "solicitud-2",
      parámetros: {
        modelo: "claude-opus-4-7",
        tokens_max: 16000,
        mensajes: [
          { rol: "usuario", contenido: "Explicar los conceptos básicos de la computación cuántica" },
        ],
      },
    },
  ],
});

console.log(`Batch ID: ${messageBatch.id}`);
consola.log(`Status: ${messageBatch.processing_status}`);

Poll for Completion

dejar lotes;
mientras (verdadero) {
  lote = espera client.messages.batches.retrieve(messageBatch.id);
  if (batch.processing_status === "finalizado") descanso;
  consola.log(
   `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
  );
  espere nueva promesa ((resolver) => setTimeout (resolver, 60_000));
}

console.log("¡Lote completo!");
console.log(`Succeeded: ${batch.request_counts.succeeded}`);
consola.log(`Errored: ${batch.request_counts.errored}`);

Retrieve Results

para await (resultado constante de await client.messages.batches.results(
  mensajeBatch.id,
)) {
  cambiar (resultado.tipo.resultado) {
    caso "tuvo éxito":
      consola.log(
       `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
      );
      romper;
    caso "error":
      if (resultado.resultado.error.tipo === "solicitud_inválida") {
        consola.log(`[${result.custom_id}] Validation error - fix and retry`);
      } más {
        consola.log(`[${result.custom_id}] Server error - safe to retry`);
      }
      romper;
    caso "caducado":
      consola.log(`[${result.custom_id}] Expired - resubmit`);
      romper;
  }
}

Cancel a Batch

const cancelado = espera client.messages.batches.cancel(messageBatch.id);
console.log(`Status: ${cancelled.processing_status}`); // "cancelando"

### mecanografiado/claude-api/files-api.md

[Descargar mecanografiado/claude-api/files-api.md](/skills/claude-api/typescript/claude-api/files-api.md)

```markdown
# Files API — TypeScript

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

## Key Facts

- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI

---

## Upload a File

```typescript
importar Anthropic, { toFile } desde "@anthropic-ai/sdk";
importar fs desde "fs";

cliente constante = nuevo Antrópico();

constante cargado = espera client.beta.files.upload({
  archivo: await toFile(fs.createReadStream("report.pdf"), indefinido, {
    escriba: "solicitud/pdf",
  }),
  betas: ["archivos-api-2025-04-14"],
});

console.log(`File ID: ${uploaded.id}`);
consola.log(`Size: ${uploaded.size_bytes} bytes`);

Use a File in Messages

PDF / Text Document

respuesta constante = esperar client.beta.messages.create({
  modelo: "claude-opus-4-7",
  tokens_max: 16000,
  mensajes: [
    {
      rol: "usuario",
      contenido: [
        { type: "text", text: "Resuma los hallazgos clave de este informe". },
        {
          tipo: "documento",
          fuente: {tipo: "archivo", file_id: uploaded.id},
          título: "Informe del cuarto trimestre",
          citas: {habilitado: verdadero},
        },
      ],
    },
  ],
  betas: ["archivos-api-2025-04-14"],
});

console.log(respuesta.content[0].text);

Manage Files

List Files

archivos constantes = esperar client.beta.files.list({
  betas: ["archivos-api-2025-04-14"],
});
para (const f de archivos.datos) {
  console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
}

Delete a File

espere client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
  betas: ["archivos-api-2025-04-14"],
});

Download a File

respuesta constante = esperar client.beta.files.download(
  "archivo_011CNha8iCJcU1wXNR6q4V8w",
  { betas: ["archivos-api-2025-04-14"] },
);
contenido constante = Buffer.from(espera respuesta.arrayBuffer());
espere fs.promises.writeFile("output.txt", contenido);

### mecanografiado/claude-api/streaming.md

[Descargar mecanografiado/claude-api/streaming.md](/skills/claude-api/typescript/claude-api/streaming.md)

```markdown
# Streaming — TypeScript

## Quick Start

```typescript
flujo constante = cliente.messages.stream({
  modelo: "claude-opus-4-7",
  tokens_max: 64000,
  mensajes: [{ rol: "usuario", contenido: "Escribir una historia" }],
});

para esperar (evento constante de la transmisión) {
  si (
    evento.tipo === "content_block_delta" &&
    evento.delta.tipo === "text_delta"
  ) {
    proceso.stdout.write(evento.delta.text);
  }
}

Handling Different Content Types

flujo constante = cliente.messages.stream({
  modelo: "claude-opus-4-7",
  tokens_max: 64000,
  pensando: {tipo: "adaptativo" },
  mensajes: [{ rol: "usuario", contenido: "Analizar este problema" }],
});

para esperar (evento constante de la transmisión) {
  cambiar (tipo.de.evento) {
    caso "content_block_start":
      cambiar (event.content_block.type) {
        caso "pensar":
          console.log("\n[Pensando...]");
          romper;
        caso "texto":
          console.log("\n[Respuesta:]");
          romper;
      }
      romper;
    caso "content_block_delta":
      cambiar (evento.tipo.delta) {
        caso "pensando_delta":
          proceso.stdout.write(evento.delta.pensamiento);
          romper;
        caso "text_delta":
          proceso.stdout.write(evento.delta.text);
          romper;
      }
      romper;
  }
}

Streaming with Tool Use (Tool Runner)

Use the tool runner with stream: true. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:

importar Anthropic desde "@anthropic-ai/sdk";
importar { betaZodTool } desde "@anthropic-ai/sdk/helpers/beta/zod";
importar {z} desde "zod";

cliente constante = nuevo Antrópico();

const getWeather = betaZodTool({
  nombre: "get_weather",
  descripción: "Obtener el clima actual para una ubicación",
  esquema de entrada: z.object({
    ubicación: z.string().describe("Ciudad y estado, por ejemplo, San Francisco, CA"),
  }),
  ejecutar: asíncrono ({ubicación}) =>`72°F and sunny in ${location}`,
});

corredor constante = cliente.beta.messages.toolRunner({
  modelo: "claude-opus-4-7",
  tokens_max: 64000,
  herramientas: [obtenerTiempo],
  mensajes: [
    { rol: "usuario", contenido: "¿Qué tiempo hace en París y Londres?" },
  ],
  corriente: verdadero,
});

// Bucle exterior: cada iteración del corredor de herramientas
para esperar (const messageStream del corredor) {
  // Bucle interno: transmitir eventos para esta iteración
  para esperar (evento constante de messageStream) {
    cambiar (tipo.de.evento) {
      caso "content_block_delta":
        cambiar (evento.tipo.delta) {
          caso "text_delta":
            proceso.stdout.write(evento.delta.text);
            romper;
          caso "input_json_delta":
            // Se transmite la entrada de la herramienta
            romper;
        }
        romper;
    }
  }
}

Getting the Final Message

flujo constante = cliente.messages.stream({
  modelo: "claude-opus-4-7",
  tokens_max: 64000,
  mensajes: [{ rol: "usuario", contenido: "Hola" }],
});

para esperar (evento constante de la transmisión) {
  // Procesar eventos...
}

const finalMessage = espera stream.finalMessage();
console.log(`Tokens used: ${finalMessage.usage.output_tokens}`);

Stream Event Types

Best Practices

1. Always flush output — Use process.stdout.write() for immediate display
2. Handle partial responses — If the stream is interrupted, you may have incomplete content
3. Track token usage — The message_delta event contains usage information
4. Use finalMessage() — Get the complete Anthropic.Message object even when streaming. Don't wrap .on() events in new Promise() — finalMessage() handles all completion/error/abort states internally
5. Buffer for web UIs — Consider buffering a few tokens before rendering to avoid excessive DOM updates
6. Use stream.on("text", ...) for deltas — The text event provides just the delta string, simpler than manually filtering content_block_delta events
7. For agentic loops with streaming — See the Streaming Manual Loop section in tool-use.md for combining stream() + finalMessage() with a tool-use loop

Raw SSE Format

If using raw HTTP (not SDKs), the stream returns Server-Sent Events:

evento: mensaje_inicio
datos: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}

evento: content_block_start
datos: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

evento: content_block_delta
datos: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hola"}}

evento: content_block_stop
datos: {"type":"content_block_stop","index":0}

evento: mensaje_delta
datos: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

evento: mensaje_parada
datos: {"tipo":"message_stop"}

### mecanografiado/claude-api/tool-use.md

[Descargar mecanografiado/claude-api/tool-use.md](/skills/claude-api/typescript/claude-api/tool-use.md)

_Recurso binario_

### mecanografiado/agentes-administrados/README.md

[Descargar mecanografiado/managed-agents/README.md](/skills/claude-api/typescript/managed-agents/README.md)

_Recurso binario_

## Ver en GitHub

[Ver en GitHub](https://github.com/anthropics/skills/tree/main/claude-api)