- 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ístrese aquí)
Configuración
1
Crear una carpeta de proyecto
Cree un nuevo directorio para este inicio rápido:Para sus propios proyectos, puede ejecutar el SDK desde cualquier carpeta; tendrá acceso a los archivos en ese directorio y sus subdirectorios de forma predeterminada.
2
Instalar el SDK
Instale el paquete del SDK de Agent para su idioma:Establecer
- TypeScript (nuevo proyecto)
- TypeScript (proyecto existente)
- Python (uv)
- Python (pip)
"type": "module" en package.json permite que su script de agente use await de nivel superior, y tsx ejecuta archivos TypeScript directamente.El SDK de TypeScript incluye un binario nativo de Claude Code para su plataforma como una dependencia opcional, por lo que no necesita instalar Claude Code por separado.
3
Establecer su clave de API
Obtenga una clave de API de la Consola de Claude, luego establézcala como una variable de entorno en el shell donde ejecutará su agente:El SDK lee la clave del entorno del proceso que ejecuta su agente; no carga archivos
- macOS / Linux
- Windows (PowerShell)
.env automáticamente. Si mantiene la clave en un archivo .env, cárguela usted mismo, por ejemplo con el paquete dotenv, antes de llamar al SDK.El SDK también admite autenticación a través de proveedores de API de terceros:- Amazon Bedrock: establezca la variable de entorno
CLAUDE_CODE_USE_BEDROCK=1y configure las credenciales de AWS - Claude Platform on AWS: establezca
CLAUDE_CODE_USE_ANTHROPIC_AWS=1yANTHROPIC_AWS_WORKSPACE_ID, luego configure las credenciales de AWS - Google Cloud’s Agent Platform: establezca la variable de entorno
CLAUDE_CODE_USE_VERTEX=1y configure las credenciales de Google Cloud - Microsoft Azure: establezca la variable de entorno
CLAUDE_CODE_USE_FOUNDRY=1y configure las credenciales de Azure
A menos que haya sido aprobado previamente, Anthropic no permite 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, utilice 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 lo guía a través de la construcción de un agente que puede encontrar y corregir errores en el código. Primero, necesita un archivo con algunos errores intencionales para que el agente corrija. Creeutils.py en el directorio my-agent y pegue el siguiente código:
calculate_average([])se bloquea con una división por ceroget_user_name(None)se bloquea con un TypeError
Construir un agente que encuentre y corrija errores
Creeagent.py si está utilizando el SDK de Python, o agent.ts para TypeScript. Use agent.mts en su lugar si su proyecto existente usa CommonJS:
-
query: el punto de entrada principal que crea el bucle agentic. Devuelve un iterador asincrónico, por lo que utilizaasync forpara transmitir mensajes mientras Claude trabaja. Consulte la API completa en la referencia del SDK de Python o TypeScript. -
prompt: lo que desea que haga Claude. Claude determina qué herramientas usar en función de la tarea. -
options: configuración para el agente. Este ejemplo utilizaallowedToolspara preautorizarRead,EdityGlob, ypermissionMode: "acceptEdits"para aprobar automáticamente los cambios de archivo. Otras opciones incluyensystemPrompt,mcpServersy más. Consulte todas las opciones para Python o TypeScript.
async for continúa 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 consuma 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ía 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 necesita salida en vivo (por ejemplo, para trabajos en segundo plano o canalizaciones de CI), puede recopilar todos los mensajes a la vez. Consulte Transmisión frente a modo de un solo turno para obtener más detalles.
Ejecutar su agente
Su agente está listo. Ejecútelo con el siguiente comando:- TypeScript
- Python (uv)
- Python (pip)
agent.mts, ejecute npx tsx agent.mts en su lugar.Done: success. Después de ejecutar, verifique utils.py. Verá código defensivo que maneja listas vacías y usuarios nulos. Su agente de forma autónoma:
- Leyó
utils.pypara 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
Si ve “API key not found”, asegúrese de haber establecido la variable de entorno
ANTHROPIC_API_KEY en el shell donde ejecuta su agente. El SDK no carga archivos .env automáticamente. Consulte la guía completa de solución de problemas para obtener más ayuda.Probar otros prompts
Ahora que su agente está configurado, pruebe 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 su agente
Puede modificar el comportamiento de su agente cambiando las opciones. Aquí hay algunos ejemplos: Agregar capacidad de búsqueda web:Bash habilitado, intente: "Write unit tests for utils.py, run them, and fix any failures"
Conceptos clave
Tools controlan lo que su agente puede hacer:
Modos de permiso controlan cuánta supervisión humana desea:
El ejemplo anterior utiliza el modo
acceptEdits, que aprueba automáticamente las operaciones de archivo para que el agente pueda ejecutarse sin indicadores interactivos. Si desea solicitar a los usuarios la aprobación, utilice el modo default y proporcione una devolución de llamada canUseTool que recopile la entrada del usuario. Para más control, consulte Permisos.
Próximos pasos
Ahora que ha creado su primer agente, aprenda cómo extender sus capacidades y adaptarlo a su caso de uso:- Permisos: controle lo que su agente puede hacer y cuándo necesita aprobación
- Hooks: ejecute código personalizado antes o después de llamadas de herramientas
- Sesiones: construya agentes de múltiples turnos que mantengan contexto
- Servidores MCP: conéctese a bases de datos, navegadores, API y otros sistemas externos
- Hosting: implemente agentes en Docker, nube e CI/CD
- Agentes de ejemplo: vea ejemplos completos: asistente de correo electrónico, agente de investigación y más