Capítulo 9: Casos de Uso Prácticos

1. Agente de Code Review

Revisa automáticamente PRs buscando bugs, seguridad y estilo.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def code_review(directorio: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        cwd=directorio,
        system_prompt="""Eres un revisor de código experto.
        Analiza el código buscando:
        - Bugs potenciales
        - Vulnerabilidades de seguridad
        - Violaciones de SOLID
        - Código duplicado
        - Funciones muy largas

        Reporta en formato:
        ## [Severidad] Archivo:Línea
        **Problema**: Descripción
        **Sugerencia**: Cómo arreglarlo"""
    )

    async for msg in query(
        prompt="Revisa todos los archivos Python en src/",
        options=options
    ):
        if hasattr(msg, 'result'):
            print(msg.result)

asyncio.run(code_review("/mi/proyecto"))

2. Agente de Soporte Técnico

Analiza logs y sugiere soluciones.

async def agente_soporte(ruta_logs: str, problema: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Bash"],
        cwd=ruta_logs,
        system_prompt="""Eres un ingeniero de soporte experto.
        Analiza logs buscando:
        - Errores y excepciones
        - Patrones de fallo
        - Causas raíz

        Proporciona:
        1. Diagnóstico
        2. Causa probable
        3. Pasos para resolver"""
    )

    async for msg in query(
        prompt=f"El usuario reporta: {problema}. Analiza los logs.",
        options=options
    ):
        if hasattr(msg, 'result'):
            return msg.result

3. Agente de Documentación

Genera documentación automática del código.

async def generar_docs(proyecto: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Glob", "Grep"],
        permission_mode="acceptEdits",
        cwd=proyecto,
        system_prompt="""Genera documentación técnica:
        - Docstrings para funciones sin documentar
        - README.md con estructura del proyecto
        - Guía de contribución
        - Ejemplos de uso"""
    )

    async for msg in query(
        prompt="Genera documentación completa para este proyecto",
        options=options
    ):
        if hasattr(msg, 'result'):
            print(msg.result)

4. Agente de Migración

Migra código de un patrón a otro.

async def migrar_codigo(
    proyecto: str,
    patron_viejo: str,
    patron_nuevo: str
):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob", "Grep", "Bash"],
        permission_mode="acceptEdits",
        cwd=proyecto,
        system_prompt=f"""Migra código de '{patron_viejo}' a '{patron_nuevo}'.
        Por cada archivo:
        1. Identifica usos del patrón viejo
        2. Aplica el patrón nuevo
        3. Verifica que compile/funcione
        4. Reporta los cambios"""
    )

    async for msg in query(
        prompt=f"Migra todos los archivos de {patron_viejo} a {patron_nuevo}",
        options=options
    ):
        print(msg)

# Ejemplo: Migrar de callbacks a async/await
asyncio.run(migrar_codigo(
    "/mi/proyecto",
    "callbacks",
    "async/await"
))

5. Agente de Testing

Escribe y ejecuta tests automáticamente.

async def agente_testing(archivo: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash", "Glob"],
        permission_mode="acceptEdits",
        system_prompt="""Eres un ingeniero de QA experto en pytest.
        Para cada función:
        1. Analiza la lógica
        2. Escribe tests unitarios
        3. Incluye casos edge
        4. Ejecuta los tests
        5. Corrige si fallan"""
    )

    async for msg in query(
        prompt=f"Escribe tests completos para {archivo}",
        options=options
    ):
        print(msg)

6. Agente de DevOps

Automatiza tareas de operaciones.

async def agente_devops(tarea: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Bash", "Write", "Glob"],
        permission_mode="acceptEdits",
        system_prompt="""Eres un ingeniero DevOps experto.
        Puedes:
        - Ejecutar comandos de diagnóstico
        - Analizar configuraciones
        - Crear scripts de automatización
        - Generar Dockerfiles y CI configs

        Siempre:
        - Explica lo que vas a hacer antes
        - Verifica el resultado después
        - Sugiere mejoras"""
    )

    async for msg in query(prompt=tarea, options=options):
        print(msg)

# Ejemplos de uso
asyncio.run(agente_devops("Crea un Dockerfile optimizado para esta app Python"))
asyncio.run(agente_devops("Configura GitHub Actions para CI/CD"))
asyncio.run(agente_devops("Analiza el uso de disco y sugiere limpieza"))

7. Agente de Investigación

Busca y sintetiza información.

async def investigar(tema: str):
    options = ClaudeAgentOptions(
        allowed_tools=["WebSearch", "WebFetch", "Read", "Write"],
        permission_mode="acceptEdits",
        system_prompt="""Eres un investigador técnico.
        Para cada tema:
        1. Busca fuentes oficiales
        2. Compara diferentes aproximaciones
        3. Resume pros y contras
        4. Proporciona ejemplos de código
        5. Guarda el resultado en un archivo markdown"""
    )

    async for msg in query(
        prompt=f"Investiga: {tema}. Crea un reporte completo.",
        options=options
    ):
        print(msg)

asyncio.run(investigar("Mejores prácticas de autenticación en FastAPI 2025"))

8. Agente de Email

Procesa y responde emails.

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("leer_emails", "Lee emails de la bandeja", {"limite": int})
async def leer_emails(args):
    # Integración con tu proveedor de email
    emails = await obtener_emails(limite=args['limite'])
    return {"content": [{"type": "text", "text": str(emails)}]}

@tool("responder_email", "Responde a un email", {"id": str, "respuesta": str})
async def responder_email(args):
    await enviar_respuesta(args['id'], args['respuesta'])
    return {"content": [{"type": "text", "text": "Email enviado"}]}

server = create_sdk_mcp_server(
    name="email",
    version="1.0.0",
    tools=[leer_emails, responder_email]
)

options = ClaudeAgentOptions(
    mcp_servers={"email": server},
    allowed_tools=["mcp__email__leer_emails", "mcp__email__responder_email"],
    system_prompt="""Procesa emails de soporte:
    - Clasifica por urgencia
    - Redacta respuestas profesionales
    - Escala si es necesario"""
)

9. Agente de Refactoring Paralelo

Ejecuta múltiples tareas en paralelo.

#!/bin/bash
# refactor_parallel.sh

# Archivos a refactorizar
FILES=$(find src -name "*.py")

# Ejecuta en paralelo
for file in $FILES; do
    python -c "
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def refactor():
    options = ClaudeAgentOptions(
        allowed_tools=['Read', 'Edit'],
        permission_mode='acceptEdits'
    )
    async for msg in query(
        prompt='Refactoriza $file aplicando principios SOLID',
        options=options
    ):
        pass

asyncio.run(refactor())
" &
done

wait
echo "Refactoring completo"

10. Agente con Interfaz Web

Expone el agente como API REST.

from fastapi import FastAPI
from claude_agent_sdk import query, ClaudeAgentOptions

app = FastAPI()

@app.post("/ask")
async def ask(pregunta: str, proyecto: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        cwd=proyecto
    )

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

    return {"respuesta": resultado}

# Ejecutar: uvicorn main:app --reload

Resumen de Casos de Uso

Caso de Uso	Herramientas Clave	Complejidad
Code Review	Read, Glob, Grep	Media
Soporte	Read, Grep, Bash	Media
Documentación	Read, Write, Glob	Baja
Migración	Read, Edit, Bash	Alta
Testing	Read, Write, Bash	Media
DevOps	Bash, Write, Read	Alta
Investigación	WebSearch, WebFetch	Media
Email	MCP Custom	Alta