¿Qué hace Construcción de Aplicaciones Potenciadas por LLM con Claude?
Este skill te ayuda a construir aplicaciones potenciadas por LLM con Claude. Elige la superficie adecuada según tus necesidades, detecta el lenguaje del proyecto y luego lee la documentación específica del lenguaje.
Antes de Empezar
Escanea el archivo objetivo (o, si no hay archivo objetivo, el prompt y el proyecto) en busca de marcadores de proveedores que no sean Anthropic — import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, nombres de archivo como agent-openai.py o *-generic.py, o cualquier instrucción explícita de mantener el código neutral respecto al proveedor. Si encuentras alguno, detente e informa al usuario que este skill produce código para Claude/SDK de Anthropic; pregúntale si quiere cambiar el archivo a Claude o si prefiere una implementación que no use Claude. No edites un archivo no-Anthropic con llamadas al SDK de Anthropic.
Requisito de Salida
Cuando el usuario te pida agregar, modificar o implementar una funcionalidad de Claude, tu código debe llamar a Claude a través de una de las siguientes opciones:
- El SDK oficial de Anthropic para el lenguaje del proyecto (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Esta es la opción predeterminada siempre que exista un SDK compatible para el proyecto. - HTTP plano (
curl,requests,fetch,httpx, etc.) — solo cuando el usuario solicite explícitamente cURL/REST/HTTP plano, el proyecto sea un proyecto de shell/cURL, o el lenguaje no tenga un SDK oficial.
Nunca mezcles los dos enfoques — no uses requests/fetch en un proyecto de Python o TypeScript solo porque parezca más ligero. Nunca recurras a shims compatibles con OpenAI.
Nunca adivines 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 de los archivos {lang}/ en este skill o de los repositorios oficiales del SDK o enlaces de documentación listados en shared/live-sources.md. Si el binding que necesitas no está documentado explícitamente en los archivos del skill, haz WebFetch del repositorio del SDK relevante desde shared/live-sources.md antes de escribir código. No infieras APIs de Ruby/Java/Go/PHP/C# a partir de formas de cURL o del SDK de otro lenguaje.
Si WebFetch o el acceso al repositorio fallan (red restringida, tiempos de espera, clon bloqueado): no sigas reintentando — escribe código basándote en los patrones y las tablas de espacios de nombres/paquetes en el archivo {lang}/, ejecuta el compilador o intérprete con ese código e itera sobre la salida de errores. Para SDKs de tipos estáticos (C#, Java, Go), un bucle de compilación-corrección contra errores locales lleva a código funcional más rápido que la investigación de red bloqueada.
Valores Predeterminados
A menos que el usuario solicite lo contrario:
Para la versión del modelo Claude, usa Claude Opus 5, al que puedes acceder mediante la cadena de modelo exacta claude-opus-5. Por defecto, usa pensamiento adaptativo (thinking: {type: "adaptive"}) para cualquier cosa remotamente compleja. Y finalmente, por defecto, usa streaming para cualquier solicitud que pueda implicar entrada larga, salida larga o max_tokens alto — esto evita superar los tiempos de espera de la solicitud. Usa el helper .get_final_message() / .finalMessage() del SDK para obtener la respuesta completa si no necesitas manejar eventos de stream individuales.
⚠️ Deriva de API — Tu Prioridad de Entrenamiento Puede Estar Desactualizada
Varias formas comunes de la API de Claude cambiaron en 2025–2026. Si recuerdas un patrón del entrenamiento, verifícalo contra los archivos {lang}/ en este skill antes de escribir — las filas siguientes son los puntos de deriva más frecuentes:
| Área | Prioridad desactualizada | API actual |
|---|---|---|
| Pensamiento extendido | thinking: {type: "enabled", budget_tokens: N} | En modelos Claude 4.6+: thinking: {type: "adaptive"}. budget_tokens está obsoleto en Opus 4.6 / Sonnet 4.6 y rechazado con un 400 en Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Los modelos anteriores a 4.6 siguen usando budget_tokens. |
| Tipo de herramienta de búsqueda web / fetch web | web_search_20250305, web_fetch_20250910 | web_search_20260209, web_fetch_20260209 (filtrado dinámico) en Opus 5/4.8/4.7/4.6, Sonnet 5 y Sonnet 4.6. Los modelos más antiguos mantienen las variantes básicas; en Vertex AI solo está disponible la web_search_20250305 básica (web fetch no está en Vertex) — consulta la QR de Server Tools a continuación. |
| Nombres de parámetros en PHP | Nombres de argumentos snake_case en la línea (max_tokens) | Los argumentos con nombre de nivel superior son camelCase (maxTokens). Las claves de arrays anidados varían según la funcionalidad (ej. 'taskBudget', 'skillID', 'mcp_server_name') — copia la clave exacta del ejemplo documentado; no hagas una conversión masiva. |
| Credenciales de Managed Agents | Mantener secretos del lado del host mediante herramientas personalizadas (la única opción antes de que se lanzaran los vaults) | Credenciales de environment_variable en Vault — almacenadas por Anthropic, sustituidas en la salida, nunca visibles en el sandbox (shared/managed-agents-tools.md → Vaults). Las herramientas personalizadas del lado del host siguen siendo la alternativa para sandboxes autoalojados. |
Los archivos {lang}/ en este skill son autoritativos sobre los patrones recordados.
Subcomandos
Si la Solicitud del Usuario al final de este prompt es una cadena de subcomando simple (sin prosa), busca en cada tabla de Subcomandos en este documento — incluyendo cualquier tabla en secciones añadidas a continuación — y sigue la columna de Acción correspondiente directamente. Esto permite a los usuarios invocar flujos específicos mediante /claude-api <subcomando>. Si ninguna tabla en el documento coincide, trata la solicitud como prosa normal.
| Subcomando | Acción |
|---|---|
migrate | Migrar código existente de la API de Claude a un modelo más nuevo. Lee shared/model-migration.md inmediatamente y síguelo en orden: Paso 0 (confirmar el alcance — preguntar qué archivos/directorios antes de cualquier edición), Paso 1 (clasificar cada archivo), luego la sección de cambios rupturistas por destino. No resumas la guía — ejecútala. Si el usuario no nombró un modelo de destino, pregunta a qué modelo migrar en el mismo turno que la pregunta de alcance. |
Detección de Lenguaje
Antes de leer ejemplos de código, determina en qué lenguaje está trabajando el usuario:
-
Mira los archivos del proyecto para inferir el lenguaje:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile→ Python — lee desdepython/*.ts,*.tsx,package.json,tsconfig.json→ TypeScript — lee desdetypescript/*.js,*.jsx(sin archivos.tspresentes) → TypeScript — JS usa el mismo SDK, lee desdetypescript/*.java,pom.xml,build.gradle→ Java — lee desdejava/*.kt,*.kts,build.gradle.kts→ Java — Kotlin usa el SDK de Java, lee desdejava/*.scala,build.sbt→ Java — Scala usa el SDK de Java, lee desdejava/*.go,go.mod→ Go — lee desdego/*.rb,Gemfile→ Ruby — lee desderuby/*.cs,*.csproj→ C# — lee desdecsharp/*.php,composer.json→ PHP — lee desdephp/
-
Si se detectan múltiples lenguajes (ej., archivos Python y TypeScript):
- Verifica a qué lenguaje se refiere el archivo o pregunta actual del usuario
- Si aún es ambiguo, pregunta: "He detectado tanto archivos Python como TypeScript. ¿Qué lenguaje estás usando para la integración con la API de Claude?"
-
Si el lenguaje no se puede inferir (proyecto vacío, sin archivos fuente o lenguaje no compatible):
- Usa AskUserQuestion con opciones: Python, TypeScript, Java, Go, Ruby, cURL/HTTP plano, C#, PHP
- Si AskUserQuestion no está disponible, usa ejemplos de Python por defecto y señala: "Mostrando ejemplos de Python. Avísame si necesitas un lenguaje diferente."
-
Si se detecta un lenguaje no compatible (Rust, Swift, C++, Elixir, etc.):
- Sugiere ejemplos de cURL/HTTP plano desde
curl/y señala que pueden existir SDKs comunitarios - Ofrece mostrar ejemplos de Python o TypeScript como implementaciones de referencia
- Sugiere ejemplos de cURL/HTTP plano desde
-
Si el usuario necesita ejemplos de cURL/HTTP plano, lee desde
curl/.
Soporte de Funcionalidades Específicas por Lenguaje
Todos los lenguajes del SDK anteriores soportan tanto el Tool Runner beta como Managed Agents (beta) — Python (@beta_tool decorador), TypeScript (betaZodTool + Zod), Java (clases anotadas), Go (BetaToolRunner en el paquete toolrunner), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + esquema JSON plano), PHP (BetaRunnableTool + toolRunner()); los puntos de entrada de código están en la referencia rápida de Patrones de Uso de Herramientas a continuación. cURL es HTTP plano (sin funcionalidades del SDK) y soporta Managed Agents.
Ejemplos de código de Managed Agents: consulta la guía de lectura en la sección
## Managed Agents (Beta)a continuación.
¿Qué Superficie Debería Usar?
Empieza simple. Por defecto, elige la capa más simple que satisfaga tus necesidades. Las llamadas únicas a la API y los flujos de trabajo cubren la mayoría de los casos de uso — solo recurre a agentes cuando la tarea realmente requiera exploración abierta guiada por el modelo. "Más simple" significa el menor código que tú posees: para un agente alojado, programado o con memoria, Managed Agents suele ser la opción más simple (sin código de bucle, sin archivos de estado, sin programador), aunque sea una plataforma más grande.
| Caso de Uso | Capa | Superficie Recomendada | Por Qué |
|---|---|---|---|
| Clasificación, resumen, extracción, Q&A | Llamada única a LLM | API de Claude | Una solicitud, una respuesta |
| Procesamiento por lotes o embeddings | Llamada única a LLM | API de Claude | Endpoints especializados |
| Pipelines de múltiples pasos con lógica controlada por código | Flujo de trabajo | API de Claude + uso de herramientas | Tú orquestas el bucle |
| Agente personalizado con tus propias herramientas | Agente | API de Claude + uso de herramientas | Máxima flexibilidad |
| Agente con estado gestionado por el servidor y espacio de trabajo | Agente | Managed Agents | Anthropic ejecuta el bucle y aloja el sandbox de ejecución de herramientas |
| Configuraciones de agente persistidas y versionadas | Agente | Managed Agents | Los agentes son objetos almacenados; las sesiones se fijan a una versión |
| Agente de múltiples turnos de larga duración con montajes de archivos | Agente | Managed Agents | Contenedores por sesión, flujo de eventos SSE, Skills + MCP |
| Agente que se ejecuta según un cronograma (cron, "cada noche") | Agente | Managed Agents — despliegues programados | Los despliegues activan sesiones autónomamente; sin programador del lado del cliente |
Nota: Managed Agents es la opción correcta cuando quieres que Anthropic ejecute el bucle del agente y aloje el contenedor donde se ejecutan las herramientas — operaciones de archivos, bash, ejecución de código, todo se ejecuta en el espacio de trabajo por sesión. Si quieres alojar el cómputo tú mismo o ejecutar tu propio tiempo de ejecución de herramientas personalizado, la API de Claude + uso de herramientas es la opción correcta — usa el Tool Runner para el bucle agéntico — sus ganchos por turno siguen dándote puertas de aprobación, registro, intercepción de errores y ejecución condicional (consulta
shared/tool-use-concepts.md) — o el bucle manual cuando quieras poseer todo el bucle tú mismo.
Acceso a proveedores en la nube. Claude Platform en AWS es operado por Anthropic con paridad de API el mismo día — consulta
shared/claude-platform-on-aws.mdpara la configuración del cliente. Para la disponibilidad por funcionalidad en Claude Platform en AWS, Amazon Bedrock, Google Vertex AI y Microsoft Foundry, consultashared/platform-availability.md— esa tabla es la única fuente de verdad en este skill; no infieras la disponibilidad desde ningún otro lugar.
Construcción de un Agente: Cuatro Enfoques
Una vez que hayas decidido que realmente necesitas un agente (uso de herramientas abierto y guiado por el modelo), hay cuatro formas distintas de construir uno. Dos preguntas independientes los separan: quién proporciona el arnés (el bucle del agente + la gestión del contexto) y quién proporciona el despliegue (la infraestructura en la que se ejecuta el agente). El Tool Runner y el Claude Agent SDK ambos proporcionan solo un arnés — tú todavía los alojas y despliegas tú mismo — por lo que es fácil confundirlos. Managed Agents (CMA) es la única opción que proporciona tanto el arnés como el despliegue gestionado; el bucle manual no proporciona ninguno.
| # | Enfoque | Tú escribes | Arnés y despliegue | Herramientas disponibles | Úsalo cuando |
|---|---|---|---|---|---|
| 1 | API de Claude — bucle manual | El bucle while stop_reason == "tool_use" tú mismo | Tú construyes el arnés; tú alojas | Solo las herramientas que tú definas | Quieres poseer el bucle completo — sin dependencia beta, o un flujo de control que no encaje en los ganchos por turno del Tool Runner |
| 2 | API de Claude — Tool Runner (client.beta.messages.tool_runner + @beta_tool / betaZodTool) | Solo las funciones de herramienta | El SDK proporciona el bucle (solo arnés); tú alojas | Solo las herramientas que tú definas | Un agente con herramientas personalizadas sin escribir el bucle a mano (la mayoría de los casos). Los ganchos por turno siguen dándote puertas de aprobación, intercepción de errores, modificación de resultados (ej. cache_control), reintentos, streaming y compactación |
| 3 | Managed Agents (REST, beta) | Configuración del agente + resultados de tus herramientas | Anthropic proporciona el arnés y aloja un sandbox por sesión (arnés + despliegue) | Sandbox alojado por Anthropic (bash, archivos, ejecución de código) + Skills/MCP + tus herramientas | Quieres que Anthropic ejecute el bucle y aloje el espacio de trabajo por sesión; configuraciones persistidas/versionadas; sesiones de larga duración |
| 4 | Claude Agent SDK — producto separado (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | Un prompt + opciones | El SDK proporciona el arnés de Claude Code + herramientas integradas (solo arnés); tú alojas | Herramientas integradas de Leer/Escribir/Editar/Bash/Glob/Grep/WebSearch/WebFetch + MCP + subagentes | Quieres un agente de codificación/sistema de archivos con pilas incluidas ejecutándose en tu propia infraestructura |
La división arnés/despliegue es el modelo mental clave: las opciones 1, 2 y 4 te dejan el despliegue a ti; solo la opción 3 (CMA) añade despliegue gestionado. Las opciones 1–3 son lo que este skill genera; la opción 4 es una biblioteca diferente con su propia documentación — consulta la desambiguación a continuación.
Tool Runner ≠ Claude Agent SDK. Suenan parecido pero son paquetes diferentes:
- Tool Runner es parte del SDK regular de la API de Anthropic (
anthropic/@anthropic-ai/sdk), accesible medianteclient.beta.messages.tool_runner. Automatiza...