Capítulo 4: Herramientas Integradas

Herramientas Disponibles

El Agent SDK incluye herramientas listas para usar:

Herramienta	Descripción
Read	Lee archivos del directorio de trabajo
Write	Crea nuevos archivos
Edit	Edita archivos existentes con precisión
Bash	Ejecuta comandos de terminal
Glob	Busca archivos por patrón
Grep	Busca contenido con regex
WebSearch	Busca en la web
WebFetch	Obtiene contenido de URLs
AskUserQuestion	Hace preguntas al usuario

Habilitando Herramientas

from claude_agent_sdk import query, ClaudeAgentOptions

# Solo herramientas de lectura
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"]
)

# Lectura y escritura
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"]
)

# Todas las herramientas
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebSearch"]
)

Read: Leer Archivos

options = ClaudeAgentOptions(allowed_tools=["Read"])

async for msg in query(
    prompt="Lee el archivo config.py y explica qué hace",
    options=options
):
    print(msg)

Write: Crear Archivos

options = ClaudeAgentOptions(
    allowed_tools=["Write"],
    permission_mode="acceptEdits"  # Auto-acepta escrituras
)

async for msg in query(
    prompt="Crea un archivo hello.py que imprima 'Hola Mundo'",
    options=options
):
    print(msg)

Edit: Editar con Precisión

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

async for msg in query(
    prompt="En main.py, cambia la función 'process' para manejar excepciones",
    options=options
):
    print(msg)

Bash: Ejecutar Comandos

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

async for msg in query(
    prompt="Ejecuta 'python --version' y 'pip list'",
    options=options
):
    print(msg)

Glob: Buscar Archivos

options = ClaudeAgentOptions(allowed_tools=["Glob"])

async for msg in query(
    prompt="Encuentra todos los archivos .py en src/",
    options=options
):
    print(msg)

Patrones comunes:

Patrón	Descripción
**/*.py	Todos los .py recursivamente
src/**/*.ts	.ts dentro de src/
*.{js,ts}	.js y .ts en raíz
test_*.py	Archivos que empiezan con test_

Grep: Buscar Contenido

options = ClaudeAgentOptions(allowed_tools=["Grep"])

async for msg in query(
    prompt="Busca todas las funciones que usan 'async def'",
    options=options
):
    print(msg)

WebSearch: Buscar en la Web

options = ClaudeAgentOptions(allowed_tools=["WebSearch"])

async for msg in query(
    prompt="Busca la documentación oficial de FastAPI",
    options=options
):
    print(msg)

WebFetch: Obtener Contenido Web

options = ClaudeAgentOptions(allowed_tools=["WebFetch"])

async for msg in query(
    prompt="Obtén el README de github.com/anthropics/claude-agent-sdk-python",
    options=options
):
    print(msg)

AskUserQuestion: Preguntas al Usuario

options = ClaudeAgentOptions(allowed_tools=["AskUserQuestion"])

async for msg in query(
    prompt="Pregúntame qué tipo de proyecto quiero crear",
    options=options
):
    print(msg)

Ejemplo: Agente de TODOs

Agente que busca y resume todos los TODOs en el código:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def buscar_todos():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        system_prompt="""Busca comentarios TODO/FIXME/HACK en el código.
        Para cada uno, reporta:
        - Archivo y línea
        - Contenido del TODO
        - Prioridad sugerida"""
    )

    async for msg in query(
        prompt="Encuentra todos los TODOs y crea un resumen",
        options=options
    ):
        if hasattr(msg, 'result'):
            print(msg.result)

asyncio.run(buscar_todos())

Ejemplo: Agente Read-Only

Agente seguro que solo puede leer:

async def agente_readonly(pregunta: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="bypassPermissions"  # No pide confirmación
    )

    async for msg in query(prompt=pregunta, options=options):
        if hasattr(msg, 'result'):
            return msg.result

Ejemplo: Automatización de Tests

async def ejecutar_tests():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Bash", "Edit"],
        permission_mode="acceptEdits",
        system_prompt="""Ejecuta los tests y si fallan:
        1. Lee el error
        2. Identifica la causa
        3. Sugiere o aplica la corrección"""
    )

    async for msg in query(
        prompt="Ejecuta pytest y corrige cualquier test que falle",
        options=options
    ):
        print(msg)

Combinaciones Recomendadas

Análisis de Código (Solo Lectura)

allowed_tools=["Read", "Glob", "Grep"]

Desarrollo Activo

allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

Investigación

allowed_tools=["Read", "Glob", "Grep", "WebSearch", "WebFetch"]

Agente Interactivo

allowed_tools=["Read", "Write", "Edit", "Bash", "AskUserQuestion"]

Resumen

• Las herramientas built-in cubren la mayoría de casos
• Usa allowed_tools para habilitar solo las necesarias
• Combina herramientas según el caso de uso
• permission_mode controla la confirmación de acciones