SDK de Claude Code

 (docs.anthropic.com)
1 puntos por GN⁺ 2025-05-20 | 1 comentarios | Compartir por WhatsApp
  • El Claude Agent SDK permite controlar desde código Python y TypeScript la ejecución de herramientas, el bucle del agente y la gestión de contexto de Claude Code, para automatizar lectura de archivos, ejecución de comandos, búsquedas web y edición de código
  • Ofrece como herramientas integradas Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, por lo que puede cubrir desde la exploración del codebase hasta preguntas de confirmación al usuario sin una capa de ejecución separada
  • Al combinar hooks, subagentes, MCP, permisos y sesiones, se pueden crear configuraciones como registros de auditoría de cambios en archivos, subagentes dedicados a revisión de código, automatización de navegador basada en Playwright y agentes de análisis en modo solo lectura
  • La instalación se hace con @anthropic-ai/claude-agent-sdk o claude-agent-sdk; Python requiere 3.10 o superior, y el SDK de TypeScript incluye como dependencia opcional un binario nativo de Claude Code para la plataforma
  • A diferencia del Anthropic Client SDK, donde se implementa directamente el bucle de herramientas, el Agent SDK ofrece ejecución integrada de herramientas y se ejecuta en el proceso e infraestructura del usuario, no en la infraestructura de Anthropic como Managed Agents

Alcance del Claude Agent SDK

  • El Claude Agent SDK permite usar desde Python y TypeScript las herramientas, el bucle del agente y la gestión de contexto que impulsan Claude Code
  • El agente puede leer archivos, ejecutar comandos, buscar en la web y editar código
  • Incluye ejecución integrada de herramientas, así que el usuario no necesita construir por su cuenta una capa separada de ejecución para que el agente empiece a trabajar
  • El ejemplo básico permite las herramientas Read, Edit y Bash para encontrar y corregir un bug en auth.py

Instalación y flujo de autenticación

  • Se instala mediante paquetes según el lenguaje
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • El paquete de Python requiere Python 3.10 o superior
    • Si aparece el error No matching distribution found for claude-agent-sdk, es posible que el intérprete sea anterior a la versión 3.10
    • En macOS o Linux se verifica con python3 --version, y en Windows con py --version
  • El SDK de TypeScript incluye como dependencia opcional un binario nativo de Claude Code para la plataforma, por lo que no hace falta instalar Claude Code por separado
  • La API key se obtiene en Console y se configura en la variable de entorno ANTHROPIC_API_KEY
  • También se admite autenticación con proveedores de API de terceros
    • Amazon Bedrock: configurar CLAUDE_CODE_USE_BEDROCK=1 y luego las credenciales de AWS
    • Claude Platform on AWS: configurar CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID y luego las credenciales de AWS
    • Google Vertex AI: configurar CLAUDE_CODE_USE_VERTEX=1 y luego las credenciales de Google Cloud
    • Microsoft Azure: configurar CLAUDE_CODE_USE_FOUNDRY=1 y luego las credenciales de Azure
  • Anthropic no permite que desarrolladores externos ofrezcan inicio de sesión con claude.ai ni rate limits para productos basados en Claude Agent SDK sin aprobación previa

Herramientas base y funciones del agente

  • El SDK permite manejar desde código las capacidades principales de Claude Code
    • herramientas integradas
    • hooks
    • subagentes
    • MCP
    • permisos
    • sesiones
  • Las principales herramientas integradas cumplen estas funciones
    • Read: leer archivos dentro del directorio de trabajo
    • Write: crear archivos nuevos
    • Edit: aplicar ediciones precisas a archivos existentes
    • Bash: ejecutar comandos de terminal, scripts y tareas de git
    • Monitor: supervisar scripts en segundo plano y reaccionar con eventos a cada línea de salida
    • Glob: buscar archivos con patrones como **/*.ts, src/**/*.py
    • Grep: buscar contenido dentro de archivos mediante expresiones regulares
    • WebSearch: buscar información reciente en la web
    • WebFetch: obtener y analizar contenido de páginas web
    • AskUserQuestion: hacer preguntas de confirmación al usuario con opciones múltiples
  • El agente de ejemplo permite Read, Glob y Grep para encontrar y resumir comentarios TODO dentro del codebase

Hooks, subagentes y MCP

  • Los hooks ejecutan código del usuario en puntos clave del ciclo de vida del agente
    • Con funciones callback se puede validar, registrar, bloquear o transformar el comportamiento del agente
    • Entre los hooks disponibles están PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit y otros
    • El ejemplo detecta operaciones Edit|Write en PostToolUse y registra cambios de archivos en audit.log
  • Los subagentes son agentes especializados que manejan subtareas enfocadas
    • El agente principal delega la tarea y el subagente devuelve el resultado
    • Los agentes personalizados se definen con descripción, prompt y herramientas a usar
    • Las llamadas a subagentes se realizan mediante la herramienta Agent, por lo que para aprobación automática hay que incluir Agent en allowedTools
    • Los mensajes dentro del contexto del subagente incluyen el campo parent_tool_use_id para rastrear a qué ejecución de subagente pertenecen
  • Con Model Context Protocol (MCP) se puede conectar con sistemas externos como bases de datos, navegadores y APIs

Gestión de permisos y sesiones

  • La configuración de permisos limita qué herramientas puede usar el agente
    • Se pueden permitir tareas seguras, bloquear tareas riesgosas y exigir aprobación para acciones sensibles
    • El ejemplo preaprueba solo Read, Glob y Grep para crear un agente de solo lectura que analiza código sin modificarlo
  • La herramienta AskUserQuestion y los prompts de aprobación interactiva se usan junto con el flujo de manejo de entrada del usuario
  • Las sesiones mantienen el contexto a lo largo de múltiples intercambios
    • Claude recuerda los archivos leídos, el análisis realizado y el historial de conversación
    • Después se puede reanudar la misma sesión o bifurcarla para explorar otro enfoque
    • El ejemplo obtiene un session_id en la primera consulta y en la segunda continúa el mismo contexto con resume=session_id

Soporte de configuración de Claude Code

  • El SDK admite la configuración basada en filesystem de Claude Code
  • Con las opciones predeterminadas carga configuración desde .claude/ en el directorio de trabajo y desde ~/.claude/
  • Para limitar las fuentes de configuración que se cargarán, se usa la opción setting_sources en Python y settingSources en TypeScript
  • Las funciones y ubicaciones compatibles son las siguientes
    • Skills: capacidades especializadas que Claude usa automáticamente o invoca con /name, en .claude/skills/*/SKILL.md
    • Commands: comandos personalizados en formato heredado, en .claude/commands/*.md
    • Memory: contexto e instrucciones del proyecto, en CLAUDE.md o .claude/CLAUDE.md
    • Plugins: amplían skills, agentes, hooks y servidores MCP; se configuran por programación con la opción plugins

Diferencias frente a otras herramientas de Claude

  • El Anthropic Client SDK ofrece acceso directo a la API, y el usuario envía prompts e implementa por su cuenta la ejecución de herramientas
  • En el Agent SDK, Claude se encarga de procesar las herramientas de forma autónoma
    • En el Client SDK, el usuario implementa el bucle de herramientas
    • El Agent SDK ofrece a Claude ejecución integrada de herramientas
  • Los criterios de elección según el caso de uso son los siguientes
    • desarrollo interactivo: CLI
    • pipelines de CI/CD: SDK
    • aplicaciones personalizadas: SDK
    • tareas puntuales: CLI
    • automatización en producción: SDK
  • Muchos equipos usan la CLI para el desarrollo diario y el SDK en producción, y los workflows se pueden mover directamente entre ambos
  • Managed Agents es una REST API alojada donde Anthropic ejecuta agentes y sandboxes
  • El Agent SDK es una librería que ejecuta el bucle del agente dentro del proceso del usuario
    • lugar de ejecución: Agent SDK corre en el proceso e infraestructura del usuario; Managed Agents en infraestructura administrada por Anthropic
    • interfaz: Agent SDK es una librería de Python o TypeScript; Managed Agents es una REST API
    • objetivo de trabajo: Agent SDK opera sobre archivos de la infraestructura del usuario; Managed Agents sobre un sandbox administrado por sesión
    • estado de sesión: Agent SDK usa JSONL en el filesystem; Managed Agents usan registros de eventos alojados por Anthropic
    • herramientas personalizadas: Agent SDK usa funciones de Python o TypeScript dentro del proceso; en Managed Agents Claude activa herramientas y el usuario devuelve el resultado de ejecución
    • casos adecuados: Agent SDK para prototipos locales y agentes con acceso directo al filesystem y servicios; Managed Agents para agentes de producción sin operar sandbox o infraestructura de sesiones, y para sesiones largas o asíncronas
  • Un camino común es crear primero un prototipo local con Agent SDK y luego migrarlo a Managed Agents en producción

Registro de cambios, reporte de bugs y branding

  • Las actualizaciones del SDK, correcciones de bugs y nuevas funciones se revisan en el changelog de cada repositorio
  • Los bugs o issues se reportan en GitHub
  • Cuando un partner integra Claude Agent SDK, el uso del branding de Claude es opcional
    • permitido: “Claude Agent”, “Claude”, “Powered by Claude”
    • prohibido: “Claude Code”, “Claude Code Agent”, arte ASCII de la marca Claude Code o elementos visuales que imiten Claude Code
    • El producto debe mantener su propio branding y no debe verse como si fuera Claude Code o un producto de Anthropic
  • El uso de Claude Agent SDK está sujeto a los Anthropic’s Commercial Terms of Service
    • salvo cuando un componente o dependencia específica indique otra licencia en el archivo LICENSE correspondiente

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-05-20
Opiniones en Hacker News

  • La dirección a la que apunta Claude Code coincide exactamente con lo que quiero en una herramienta de programación agéntica, y también me gusta su filosofía tipo “herramienta Unix”
    La he usado desde el inicio de la vista previa pública y ya se veía hacia dónde iba. Creo que el estado final ideal de un agente de código es que le des una solicitud de funcionalidad, como un ticket de Jira, la revise y te genere un PR para dar feedback. En ese sentido, herramientas centradas en editores locales como Cursor o Windsurf se acercan a un callejón sin salida porque no pueden ejecutarse dentro de CI. Si vas a acondicionar el codebase para la IA con reglas, MCP y demás, entonces deberías apuntar a tecnología que también pueda usarse en modo headless. Claude Code se puede usar fácilmente como parte de la automatización mediante herramientas, así que ahora se volvió mi opción por defecto cuando pienso en agentes de código, y el paquete npm de Codex es parecido. Dicho eso, trabajo ayudando a empresas a adaptar sus codebases para el uso de agentes, así que quizá tengo sesgo hacia herramientas fáciles de configurar

    • Me cuesta estar de acuerdo con ese “estado final ideal”. Lo que yo quiero es estar en una habitación rodeado de varias pantallas, con agentes de IA programando, diseñando y probando, mientras yo estoy al centro marcando la dirección y aplicando mi criterio
      Espero una forma de trabajo completamente conversacional, donde en el 99% de los casos no haga falta tocar el teclado
    • No lo creo. El estado final “ideal” de un agente de código es un agente de programación libre y de código abierto que corra en mi computadora o en la máquina que yo quiera
      Si imaginas pagar dinero cada vez que ejecutas comandos como ls, ps o kill en la terminal, no tiene sentido. Con los LLM pasa lo mismo. No digo que haya que prohibir los LLM propietarios, pero la herramienta principal de los hackers, como antes, debería ser libre y de código abierto
    • Anthropic también anunció hoy una función beta en una dirección parecida: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • También he probado hacer esto con Cursor y MCP. Después de más o menos un día, pegué con el límite de uso y me bajaron al modelo más lento y más tonto
      También lo probé con Claude, pero consumí el límite muy rápido. Solo alrededor del 25% de los PR quedan en un nivel de “listo para fusionar” de inmediato, y muchas veces es más rápido hacerlo bien uno mismo que perder tiempo buscando dónde metió la pata la IA
    • Entiendo la idea de que te genere un PR para revisar a partir de una solicitud de funcionalidad, pero entonces solo quedaría la parte más desgastante del trabajo de software: los tickets de Jira, y eso deprime

  • Claude Code es la forma que más me gusta de usar LLM para programar
    Pero creo que lo que de verdad hace falta es una versión de código abierto donde puedas conectar cualquier modelo y comparar respuestas entre varios. Aider y otras alternativas no se sienten tan agradables de usar como Claude Code. Desde la perspectiva de Anthropic no lo querrían porque perderían su foso competitivo, pero desde la del consumidor uno solo quiere usar el mejor modelo sin quedar atado a un ecosistema específico. Probablemente ese sea justo el punto que más temen los proveedores de modelos LLM

    • OpenAI Codex probablemente sea la alternativa más cercana. Es de código abierto y puede usar modelos de cualquier proveedor
      Por ahora no es tan bueno como Claude Code, pero parece que lo alcanzará pronto. https://github.com/openai/codex/tree/main
    • El proyecto OpenCode podría interesarte: https://github.com/opencode-ai/opencode
      Sigue en desarrollo, pero se ve prometedor
    • Me da curiosidad qué es lo que Claude Code hace mejor que Aider
    • Últimamente sí he hecho demasiada autopromoción, pero si ves mis comentarios anteriores, tengo un servicio hecho en Go. Apunta exactamente a este tipo de necesidad
    • Estoy de acuerdo, pero ¿no tendrían que estar entrenados también otros modelos para saber trabajar con servidores MCP? ¿O no sería un problema?

  • Aider ha soportado Python y scripting de shell desde hace mucho tiempo [0]
    Recientemente, mientras añadían soporte para 130 lenguajes de programación nuevos, también hicieron un screencast usando Aider para scripting Bash improvisado [1]. Da una idea de lo potente que puede ser este enfoque.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Me gusta muchísimo Aider. Pronto también tendrá soporte para MCP, y estoy probando la rama de desarrollo
      Entonces podrás usar el modelo en el que confíes para desarrollar de principio a fin mediante PR, tickets y demás
    • Me pregunto qué tan cerca se puede llevar Aider de Claude Code. La experiencia de usuario de Claude Code me gustó, pero no lo uso porque prefiero Gemini 2.5 Pro
      Tampoco me entusiasma mucho que haga commits; sobre todo me gusta cómo se siente usar Claude Code
    • Aider podría mejorar muchísimo con un workflow de GitHub Actions bien pulido
      Algo como agregar solo un archivo al repositorio para poder conversar con cualquier modelo a través de issues

  • El equipo de Claude Code lo cubrió con más detalle aquí: http://latent.space/p/claude-code
    Basta con hojear la transcripción, pero personalmente me impresionó que empleados de Anthropic, incluso usando Claude ilimitado, gasten en promedio alrededor de 6 dólares al día; que vean Claude Code headless como una utilidad de “Linux” para usar en CI en cualquier parte; que lo vean como una plataforma extensible por el usuario; que sandboxing, branching y funciones de planificación estén en la hoja de ruta futura; y que consideren Sonnet 3.7 como un modelo de agente persistente

    • En el enlace dice que entre los ingenieros internos de Anthropic hubo alguien que gastó más de 1,000 dólares en un día
      Me da curiosidad cuánto serán el P50, P75 y P95 del gasto por empleado
    • Tal vez lo estoy usando mal, pero si uso Claude Code durante 2 horas, fácilmente se me van más de 20 dólares
      Es demasiado caro para proyectos personales, así que dejé de usarlo
    • Últimamente he estado disfrutando mucho el pódcast de latent space. Casi no veo personas o pódcasts que mantengan una relación señal/ruido tan alta y aun así produzcan tanto en general
      Sorprende que, mientras han hecho crecer varios negocios en el último medio año o últimos años, la cantidad y el valor de su trabajo público sigan aumentando. Ojalá otros también pudieran encontrar una curva de productividad parecida. Más o menos comparten qué les funciona, pero no es fácil de replicar. Me vienen a la mente simonw y gwern
    • Me pregunto qué tan neutral fue ese pódcast, o si simplemente fue promoción de ventas de este producto

  • Si yo hiciera un asistente de código con IA, atarme a un proveedor de modelos base sería lo último que haría
    Para que este producto tenga éxito, hace falta asumir que el rendimiento de los modelos ya entró en una meseta, que todos los modelos base convergerán a casi el mismo rendimiento y capacidades, y que los integradores elegirán por pequeñas comodidades como un SDK familiar

    • Fuera de los comandos y argumentos, no hay tantas partes que te aten. Al final solo son entrada y salida
      Se puede cambiar por otra cosa o ponerle un wrapper. Aquí no hay tanta complejidad
    • En este momento, Claude Code es el factor de diferenciación de software en el espacio de coding agéntico
      Estoy construyendo algo relacionado con asistentes de código con IA, y estaba hackeando maneras de integrar Claude Code. Es lo primero sobre lo que queríamos construir. Es demasiado pronto para preocuparse por el lock-in; necesitamos lo mejor, así que construiríamos solo alrededor de lo mejor

  • Claude Code ya podía usarse en modo no conversacional, y por lo tanto integrarse en otras apps como cualquier otra utilidad de línea de comandos de Unix
    Este SDK parece soportar por ahora solo el uso por línea de comandos, así que ¿no es lo mismo que ya existía? No me queda claro qué es lo nuevo realmente. ¿Se me está escapando algo?

    • Yo tampoco lo sé. Me parece raro que casi nadie esté hablando de este punto

  • También recomiendo Codebuff(https://www.codebuff.com/). Es un excelente asistente de código por CLI similar a Claude Code y puede ahorrar bastante en costos de tokens
    No tengo relación con este proyecto, solo soy usuario

  • En los términos dice que “no se puede usar para desarrollar productos o servicios que compitan con el servicio, para desarrollar o entrenar algoritmos o modelos de inteligencia artificial o aprendizaje automático, ni para revender el servicio”
    Me pregunto qué demonios sería un producto o servicio de software que no compita con la inteligencia general. Están vendiendo inteligencia y, si se interpreta estrictamente, le están poniendo una cláusula legal de no usarlo en ninguna parte. ¿Es tan ambiguo que no se puede hacer cumplir? Si no se puede usar para competir con la inteligencia general, ¿entonces cómo se supone que uno posee los resultados? ¿Es una de esas cosas de “a nadie le importan los términos legales”? Si a nadie le importan, ¿por qué poner una prohibición tan amplia sobre el uso del servicio? Tengo demasiadas dudas sobre si de verdad se espera que uno acepte incluso la responsabilidad de perder una demanda para recibir este tipo de resultados

    • Eso pasa cuando se deja a los abogados escribir lo que quieran
    • Cambiaron “artificial” por “general”, así que el significado obviamente cambió

  • El lock-in del modelo sería una gran desventaja de uso. Si alguien saca el nuevo mejor modelo y tú ya invertiste en esta infraestructura, te quedas atrapado
    Aunque después lo abran, es muy probable que ese modelo haya sido entrenado específicamente para ese CLI, así que puede que no funcione bien. Basta ver Codex CLI: se puede usar Gemini 2.5 Pro, pero comparado con los modelos de OpenAI, se detiene o falla al azar mucho más seguido

  • La nueva GitHub Action es exactamente la función que estaba buscando: https://docs.anthropic.com/en/docs/claude-code/github-action...
    Pero no parece haber forma de usarlo con el plan Max de Claude Code. Por lo que veo, solo acepta API keys