SpyBara
Go Premium

agent-sdk/quickstart.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

333 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Inicio rápido

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

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

Lo que hará:

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

Requisitos previos

Configuración

1

Crear una carpeta de proyecto

Cree un nuevo directorio para este inicio rápido:

mkdir my-agent && cd my-agent

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:

npm install @anthropic-ai/claude-agent-sdk
3

Establecer su clave de API

Obtenga una clave de API de la Consola de Claude, luego cree un archivo .env en su directorio de proyecto:

ANTHROPIC_API_KEY=your-api-key

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=1 y configure las credenciales de AWS
  • Google Vertex AI: establezca la variable de entorno CLAUDE_CODE_USE_VERTEX=1 y configure las credenciales de Google Cloud
  • Microsoft Azure: establezca la variable de entorno CLAUDE_CODE_USE_FOUNDRY=1 y configure las credenciales de Azure

Consulte las guías de configuración para Bedrock, Vertex AI, o Azure AI Foundry para obtener más detalles.

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. Cree utils.py en el directorio my-agent y pegue 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:

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

Construir un agente que encuentre y corrija errores

Cree agent.py si está utilizando el SDK de Python, o agent.ts para TypeScript:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
# Agentic loop: streams messages as Claude works
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use
permission_mode="acceptEdits",  # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)  # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}")  # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

Este código tiene tres partes principales:

  1. query: el punto de entrada principal que crea el bucle agentic. Devuelve un iterador asincrónico, por lo que utiliza async for para transmitir mensajes mientras Claude trabaja. Consulte la API completa en la referencia del SDK de Python o TypeScript.

  2. prompt: lo que desea que haga Claude. Claude determina qué herramientas usar en función de la tarea.

  3. options: configuración para el agente. Este ejemplo utiliza allowedTools para preautorizar Read, Edit y Glob, y permissionMode: "acceptEdits" para aprobar automáticamente los cambios de archivo. Otras opciones incluyen systemPrompt, mcpServers y más. Consulte todas las opciones para Python o TypeScript.

El bucle 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.

Ejecutar su agente

Su agente está listo. Ejecútelo con el siguiente comando:

python3 agent.py

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:

  1. Leyó utils.py para entender el código
  2. Analizó la lógica e identificó casos extremos que causarían bloqueos
  3. 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 pedirle que las implemente.

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:

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

Dar 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, intente: "Write unit tests for utils.py, run them, and fix any failures"

Conceptos clave

Tools controlan lo que su 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

Modos de permiso controlan cuánta supervisión humana desea:

Modo Comportamiento Caso de uso
acceptEdits Aprueba automáticamente ediciones de archivo y comandos comunes del sistema de archivos, pregunta por otras acciones Flujos de trabajo de desarrollo confiables
dontAsk Deniega cualquier cosa que no esté en allowedTools Agentes sin cabeza bloqueados
auto (solo TypeScript) Un clasificador de modelo aprueba o deniega cada llamada de herramienta Agentes autónomos con protecciones de seguridad
bypassPermissions Ejecuta cada herramienta sin indicadores CI en sandbox, entornos completamente confiables
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 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.

Solución de problemas

Error de API thinking.type.enabled no es compatible con este modelo

Claude Opus 4.7 reemplaza thinking.type.enabled con thinking.type.adaptive. Las versiones anteriores del SDK de Agent fallan con el siguiente error de API cuando selecciona claude-opus-4-7:

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

Actualice a la versión 0.2.111 o posterior del SDK de Agent para usar Opus 4.7.

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