Agent SDK

Inicio rápido

Comienza con el SDK de Agent de Python o TypeScript para construir agentes de IA que funcionen de forma autónoma

Utiliza el SDK de Agent para construir un agente de IA que lea tu código, encuentre errores y los corrija, todo sin intervención manual.

Lo que harás:

Configurar un proyecto con el SDK de Agent
Crear un archivo con código con errores
Ejecutar un agente que encuentre y corrija los errores automáticamente

Requisitos previos

Node.js 18+ o Python 3.10+
Una cuenta de Anthropic (regístrate aquí)

Configuración

Instalar Claude Code
El SDK de Agent utiliza Claude Code como su tiempo de ejecución. Instálalo para tu plataforma:
Después de instalar Claude Code en tu máquina, ejecuta claude en tu terminal y sigue las indicaciones para autenticarte. El SDK utilizará esta autenticación automáticamente.
Para más información sobre la instalación de Claude Code, consulta Configuración de Claude Code.
Crear una carpeta de proyecto
Crea un nuevo directorio para este inicio rápido:
mkdir my-agent && cd my-agent
Para tus propios proyectos, puedes ejecutar el SDK desde cualquier carpeta; tendrá acceso a los archivos en ese directorio y sus subdirectorios de forma predeterminada.
Instalar el SDK
Instala el paquete del SDK de Agent para tu lenguaje:
Establecer tu clave de API
Si ya has autenticado Claude Code (ejecutando claude en tu terminal), el SDK utiliza esa autenticación automáticamente.
De lo contrario, necesitas una clave de API, que puedes obtener de la Consola de Anthropic.
Crea un archivo .env en tu directorio de proyecto y almacena la clave de API allí:
ANTHROPIC_API_KEY=your-api-key
¿Usas Amazon Bedrock, Google Vertex AI o Microsoft Azure? Consulta las guías de configuración para Bedrock, Vertex AI, o Azure AI Foundry.
A menos que haya sido aprobado previamente, no permitimos que desarrolladores de terceros ofrezcan inicio de sesión en Claude.ai o límites de velocidad para sus productos, incluidos los agentes construidos en el SDK de Agent de Claude. Por favor, utiliza los métodos de autenticación de clave de API descritos en este documento en su lugar.

Crear un archivo con errores

Este inicio rápido te guía a través de la construcción de un agente que puede encontrar y corregir errores en el código. Primero, necesitas un archivo con algunos errores intencionales para que el agente corrija. Crea utils.py en el directorio my-agent y pega el siguiente código:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Este código tiene dos errores:

calculate_average([]) se bloquea con una división por cero
get_user_name(None) se bloquea con un TypeError

Construir un agente que encuentre y corrija errores

Crea agent.py si estás usando el SDK de Python, o agent.ts para TypeScript:

Este código tiene tres partes principales:

query: el punto de entrada principal que crea el bucle agentic. Devuelve un iterador asincrónico, por lo que usas async for para transmitir mensajes mientras Claude trabaja. Consulta la API completa en la referencia del SDK de Python o TypeScript.
prompt: lo que quieres que haga Claude. Claude determina qué herramientas usar en función de la tarea.
options: configuración para el agente. Este ejemplo usa allowedTools para restringir Claude a Read, Edit y Glob, y permissionMode: "acceptEdits" para aprobar automáticamente los cambios de archivo. Otras opciones incluyen systemPrompt, mcpServers y más. Consulta todas las opciones para Python o .

El bucle async for sigue ejecutándose mientras Claude piensa, llama a herramientas, observa resultados y decide qué hacer a continuación. Cada iteración produce un mensaje: el razonamiento de Claude, una llamada a herramienta, un resultado de herramienta o el resultado final. El SDK maneja la orquestación (ejecución de herramientas, gestión de contexto, reintentos) para que solo consumas el flujo. El bucle termina cuando Claude completa la tarea o encuentra un error.

El manejo de mensajes dentro del bucle filtra la salida legible por humanos. Sin filtrado, verías objetos de mensaje sin procesar, incluida la inicialización del sistema y el estado interno, lo que es útil para depuración pero ruidoso de otra manera.

Este ejemplo utiliza transmisión para mostrar el progreso en tiempo real. Si no necesitas salida en vivo (por ejemplo, para trabajos en segundo plano o canalizaciones de CI), puedes recopilar todos los mensajes a la vez. Consulta Transmisión vs. modo de un solo turno para más detalles.

Ejecutar tu agente

Tu agente está listo. Ejecútalo con el siguiente comando:

python3 agent.py

Después de ejecutar, verifica utils.py. Verás código defensivo que maneja listas vacías y usuarios nulos. Tu agente de forma autónoma:

Leyó utils.py para entender el código
Analizó la lógica e identificó casos extremos que causarían bloqueos
Editó el archivo para agregar manejo de errores adecuado

Esto es lo que hace diferente al SDK de Agent: Claude ejecuta herramientas directamente en lugar de pedirte que las implementes.

Si ves "Claude Code not found", instala Claude Code y reinicia tu terminal. Para "API key not found", establece tu clave de API. Consulta la guía completa de solución de problemas para más ayuda.

Prueba otros prompts

Ahora que tu agente está configurado, prueba algunos prompts diferentes:

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

Personalizar tu agente

Puedes modificar el comportamiento de tu agente cambiando las opciones. Aquí hay algunos ejemplos:

Agregar capacidad de búsqueda web:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Dale a Claude un prompt de sistema personalizado:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines."
)

Ejecutar comandos en la terminal:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Con Bash habilitado, prueba: "Write unit tests for utils.py, run them, and fix any failures"

Conceptos clave

Las herramientas controlan lo que tu agente puede hacer:

Herramientas	Lo que el agente puede hacer
`Read`, `Glob`, `Grep`	Análisis de solo lectura
`Read`, `Edit`, `Glob`	Analizar y modificar código
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Automatización completa

Los modos de permisos controlan cuánta supervisión humana deseas:

Modo	Comportamiento	Caso de uso
`acceptEdits`	Aprueba automáticamente ediciones de archivo, pide otras acciones	Flujos de trabajo de desarrollo confiables
`bypassPermissions`	Se ejecuta sin indicaciones	Canalizaciones de CI/CD, automatización
`default`	Requiere una devolución de llamada `canUseTool` para manejar la aprobación	Flujos de aprobación personalizados

El ejemplo anterior utiliza el modo acceptEdits, que aprueba automáticamente las operaciones de archivo para que el agente pueda ejecutarse sin indicaciones interactivas. Si deseas solicitar a los usuarios aprobación, utiliza el modo default y proporciona una devolución de llamada canUseTool que recopile entrada del usuario. Para más control, consulta Permisos.

Próximos pasos

Ahora que has creado tu primer agente, aprende cómo extender sus capacidades y adaptarlo a tu caso de uso:

Permisos: controla lo que tu agente puede hacer y cuándo necesita aprobación
Hooks: ejecuta código personalizado antes o después de llamadas a herramientas
Sesiones: construye agentes de múltiples turnos que mantengan contexto
Servidores MCP: conéctate a bases de datos, navegadores, APIs y otros sistemas externos
Hosting: despliega agentes en Docker, nube y CI/CD
Agentes de ejemplo: consulta ejemplos completos: asistente de correo electrónico, agente de investigación y más

Agent SDK

Inicio rápido

Comienza con el SDK de Agent de Python o TypeScript para construir agentes de IA que funcionen de forma autónoma

Utiliza el SDK de Agent para construir un agente de IA que lea tu código, encuentre errores y los corrija, todo sin intervención manual.

Lo que harás:

Configurar un proyecto con el SDK de Agent
Crear un archivo con código con errores
Ejecutar un agente que encuentre y corrija los errores automáticamente

Requisitos previos

Node.js 18+ o Python 3.10+
Una cuenta de Anthropic (regístrate aquí)

Configuración

Instalar Claude Code
El SDK de Agent utiliza Claude Code como su tiempo de ejecución. Instálalo para tu plataforma:
Después de instalar Claude Code en tu máquina, ejecuta claude en tu terminal y sigue las indicaciones para autenticarte. El SDK utilizará esta autenticación automáticamente.
Para más información sobre la instalación de Claude Code, consulta Configuración de Claude Code.
Crear una carpeta de proyecto
Crea un nuevo directorio para este inicio rápido:
mkdir my-agent && cd my-agent
Para tus propios proyectos, puedes ejecutar el SDK desde cualquier carpeta; tendrá acceso a los archivos en ese directorio y sus subdirectorios de forma predeterminada.
Instalar el SDK
Instala el paquete del SDK de Agent para tu lenguaje:
Establecer tu clave de API
Si ya has autenticado Claude Code (ejecutando claude en tu terminal), el SDK utiliza esa autenticación automáticamente.
De lo contrario, necesitas una clave de API, que puedes obtener de la Consola de Anthropic.
Crea un archivo .env en tu directorio de proyecto y almacena la clave de API allí:
ANTHROPIC_API_KEY=your-api-key
¿Usas Amazon Bedrock, Google Vertex AI o Microsoft Azure? Consulta las guías de configuración para Bedrock, Vertex AI, o Azure AI Foundry.
A menos que haya sido aprobado previamente, no permitimos que desarrolladores de terceros ofrezcan inicio de sesión en Claude.ai o límites de velocidad para sus productos, incluidos los agentes construidos en el SDK de Agent de Claude. Por favor, utiliza los métodos de autenticación de clave de API descritos en este documento en su lugar.

Crear un archivo con errores

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Este código tiene dos errores:

calculate_average([]) se bloquea con una división por cero
get_user_name(None) se bloquea con un TypeError

Construir un agente que encuentre y corrija errores

Crea agent.py si estás usando el SDK de Python, o agent.ts para TypeScript:

Este código tiene tres partes principales:

query: el punto de entrada principal que crea el bucle agentic. Devuelve un iterador asincrónico, por lo que usas async for para transmitir mensajes mientras Claude trabaja. Consulta la API completa en la referencia del SDK de Python o TypeScript.
prompt: lo que quieres que haga Claude. Claude determina qué herramientas usar en función de la tarea.
options: configuración para el agente. Este ejemplo usa allowedTools para restringir Claude a Read, Edit y Glob, y permissionMode: "acceptEdits" para aprobar automáticamente los cambios de archivo. Otras opciones incluyen systemPrompt, mcpServers y más. Consulta todas las opciones para Python o .

Ejecutar tu agente

Tu agente está listo. Ejecútalo con el siguiente comando:

python3 agent.py

Después de ejecutar, verifica utils.py. Verás código defensivo que maneja listas vacías y usuarios nulos. Tu agente de forma autónoma:

Leyó utils.py para entender el código
Analizó la lógica e identificó casos extremos que causarían bloqueos
Editó el archivo para agregar manejo de errores adecuado

Esto es lo que hace diferente al SDK de Agent: Claude ejecuta herramientas directamente en lugar de pedirte que las implementes.

Si ves "Claude Code not found", instala Claude Code y reinicia tu terminal. Para "API key not found", establece tu clave de API. Consulta la guía completa de solución de problemas para más ayuda.

Prueba otros prompts

Ahora que tu agente está configurado, prueba algunos prompts diferentes:

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

Personalizar tu agente

Puedes modificar el comportamiento de tu agente cambiando las opciones. Aquí hay algunos ejemplos:

Agregar capacidad de búsqueda web:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Dale a Claude un prompt de sistema personalizado:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines."
)

Ejecutar comandos en la terminal:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Con Bash habilitado, prueba: "Write unit tests for utils.py, run them, and fix any failures"

Conceptos clave

Las herramientas controlan lo que tu agente puede hacer:

Herramientas	Lo que el agente puede hacer
`Read`, `Glob`, `Grep`	Análisis de solo lectura
`Read`, `Edit`, `Glob`	Analizar y modificar código
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Automatización completa

Los modos de permisos controlan cuánta supervisión humana deseas:

Modo	Comportamiento	Caso de uso
`acceptEdits`	Aprueba automáticamente ediciones de archivo, pide otras acciones	Flujos de trabajo de desarrollo confiables
`bypassPermissions`	Se ejecuta sin indicaciones	Canalizaciones de CI/CD, automatización
`default`	Requiere una devolución de llamada `canUseTool` para manejar la aprobación	Flujos de aprobación personalizados

Próximos pasos

Ahora que has creado tu primer agente, aprende cómo extender sus capacidades y adaptarlo a tu caso de uso:

Permisos: controla lo que tu agente puede hacer y cuándo necesita aprobación
Hooks: ejecuta código personalizado antes o después de llamadas a herramientas
Sesiones: construye agentes de múltiples turnos que mantengan contexto
Servidores MCP: conéctate a bases de datos, navegadores, APIs y otros sistemas externos
Hosting: despliega agentes en Docker, nube y CI/CD
Agentes de ejemplo: consulta ejemplos completos: asistente de correo electrónico, agente de investigación y más