Crear agente de IA con Claude: Proyectos, API y Agent SDK

Para crear un agente de IA con Claude tienes tres niveles: (1) un asistente sin código con Proyectos en claude.ai, con instrucciones, archivos y conectores; (2) un agente propio con la API de Anthropic y tool use (Claude decide qué funciones tuyas llamar); y (3) un agente más autónomo con el Claude Agent SDK, que trae herramientas listas para leer archivos, ejecutar comandos y trabajar en varios pasos. Abajo tienes cuándo usar cada uno y ejemplos en Python.

Nivel 1: Proyectos en claude.ai (sin código)

Un Proyecto es un espacio con instrucciones y documentos propios que Claude usa en todas las conversaciones de ese proyecto.

1. Entra a claude.ai → Proyectos → Crear proyecto.
2. Escribe las instrucciones del proyecto:

Eres el asistente de cotizaciones de Aceros del Norte.
Usa solo la lista de precios adjunta. Si un producto no está, dilo.
Formato: tabla con producto, cantidad, precio unitario y total.

3. Sube el conocimiento: lista de precios, condiciones comerciales, fichas técnicas.
4. Si tu plan lo permite, activa conectores (por ejemplo, Google Drive o Gmail) para que consulte información actualizada.
5. Comparte el proyecto con tu equipo si tienes plan de equipo.

Qué planes incluyen qué cambia; revisa claude.com/pricing y nuestra guía de Claude para empresas: precio. Si lo que quieres es un asistente personalizado tipo GPT, también ve GPT personalizado en Claude.

Límite: vive dentro de claude.ai y depende de que una persona le escriba.

Nivel 2: agente con la API y tool use

Aquí el agente corre en tu sistema: lo puedes conectar a WhatsApp, a tu base de datos o a un proceso automático. Defines herramientas (funciones con descripción) y Claude decide cuándo usarlas.

# pip install anthropic
import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY
MODELO = "claude-sonnet-5-5"    # revisa el modelo vigente en docs.anthropic.com

PRECIOS = {"varilla 3/8": 180.0, "malla 6x6": 950.0}

herramientas = [{
    "name": "buscar_precio",
    "description": "Devuelve el precio unitario en MXN de un producto del catálogo.",
    "input_schema": {
        "type": "object",
        "properties": {"producto": {"type": "string"}},
        "required": ["producto"],
    },
}]

def ejecutar(nombre, args):
    if nombre == "buscar_precio":
        p = PRECIOS.get(args["producto"].lower())
        return f"{p} MXN" if p else "no encontrado"

mensajes = [{"role": "user", "content": "Cotiza 20 varillas 3/8 y 5 mallas 6x6"}]

while True:
    r = client.messages.create(
        model=MODELO, max_tokens=1024, tools=herramientas, messages=mensajes,
        system="Eres un cotizador. Usa buscar_precio; no inventes precios.",
    )
    mensajes.append({"role": "assistant", "content": r.content})
    if r.stop_reason != "tool_use":
        print(next(b.text for b in r.content if b.type == "text"))
        break
    resultados = [
        {"type": "tool_result", "tool_use_id": b.id, "content": ejecutar(b.name, b.input)}
        for b in r.content if b.type == "tool_use"
    ]
    mensajes.append({"role": "user", "content": resultados})

Ese while es el “ciclo del agente”: Claude pide herramientas, tú las ejecutas y le devuelves el resultado hasta que da la respuesta final. Documentación: Tool use.

Nivel 3: Claude Agent SDK

El Claude Agent SDK es la base sobre la que está construido Claude Code, empaquetada para que la uses en tus propios agentes. Trae herramientas integradas (leer y editar archivos, buscar, ejecutar comandos) y manejo del ciclo y del contexto.

# pip install claude-agent-sdk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    opciones = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep"],  # solo lectura: permisos mínimos
        system_prompt="Revisas facturas en la carpeta ./facturas y resumes montos por proveedor.",
    )
    async for mensaje in query(prompt="Resume las facturas de octubre", options=opciones):
        print(mensaje)

asyncio.run(main())

Los nombres de opciones pueden cambiar entre versiones; revisa la documentación del Agent SDK. Si te interesa la herramienta para programar, mira qué es Claude Code.

Conectar herramientas con MCP

MCP (Model Context Protocol) es un estándar abierto para conectar modelos con herramientas y datos. En lugar de programar cada integración, usas un “servidor MCP” (ya existen para Drive, Slack, bases de datos, GitHub y muchos más) y Claude lo usa. Funciona en claude.ai (como conectores), en Claude Code y en el Agent SDK. Información en modelcontextprotocol.io.

Ejemplos de agentes que tienen sentido con Claude

Un agente vale la pena cuando la tarea tiene varios pasos y cada caso es un poco distinto. Algunos ejemplos concretos y el nivel que suelen necesitar:

• Cotizador por WhatsApp (nivel 2): entiende lo que pide el cliente aunque lo escriba con errores, consulta precios e inventario en tu sistema con herramientas y arma la cotización. El precio siempre sale de tu base de datos, nunca de la memoria del modelo.
• Revisor de contratos o expedientes (nivel 1 o 3): compara un documento contra tu checklist interna y marca lo que falta. Claude maneja bien documentos largos, lo que ayuda en este tipo de tarea.
• Conciliador de facturas (nivel 3): lee una carpeta de XML y PDF, cruza contra un Excel de pagos y deja un reporte de diferencias para que una persona lo revise.
• Asistente de soporte interno (nivel 1 con conectores, o nivel 2): responde dudas del equipo con los manuales y, si hace falta, abre un ticket.

Cuándo no necesitas un agente

Si el proceso es siempre igual —“cuando llegue un correo con factura, guarda el adjunto en Drive y avisa por Slack”— no necesitas que un modelo decida nada. Una automatización con pasos fijos es más barata, más rápida y más fácil de depurar. Herramientas como n8n permiten meter un paso de IA solo donde hace falta (por ejemplo, clasificar el correo) dentro de un flujo fijo; lo explicamos en automatizar procesos con n8n.

La regla práctica: usa un agente cuando no puedes escribir de antemano todos los pasos. Si puedes, escribe los pasos.

Cómo probar tu agente antes de soltarlo

1. Junta casos reales: 20 o 30 peticiones verdaderas, incluidas las raras y las que deberían rechazarse.
2. Registra cada paso: guarda qué herramienta llamó, con qué datos y qué respondió. Cuando algo sale mal, ese registro te dice si el problema fue el modelo, la herramienta o tus instrucciones.
3. Separa leer de actuar: las herramientas que consultan pueden correr solas; las que mandan, cobran, borran o modifican, que pidan confirmación de una persona al principio.
4. Vuelve a probar al cambiar de modelo: Anthropic publica modelos nuevos con frecuencia y el comportamiento cambia. Corre tus casos antes de actualizar el nombre del modelo en producción.

Antes de mandarle datos de clientes, revisa las condiciones de uso comercial y de privacidad de Anthropic para tu tipo de cuenta, y lo que exige la ley de protección de datos para tu caso.

Cuál elegir

Necesitas	Usa
Asistente para tu equipo con documentos	Proyectos en claude.ai
Agente en WhatsApp o tu sistema con tus funciones	API + tool use
Agente que trabaja con archivos, código o comandos	Claude Agent SDK
Conectar con apps existentes sin programar integraciones	MCP

Errores comunes

• Dar todas las herramientas “por si acaso”: empieza con solo lectura.
• No limitar pasos ni gasto: pon un máximo de vueltas al ciclo y un límite en la consola de Anthropic.
• Llave de API en el código: usa variables de entorno.
• Confiar en texto externo: si el agente lee correos o webs, puede recibir instrucciones maliciosas; las acciones delicadas deben requerir aprobación humana.

Para cerrar

Claude es una buena base para agentes que trabajan con documentos largos y tareas de varios pasos. Empieza con un Proyecto para validar la idea y pasa a la API cuando necesites que corra solo. En crear agente de IA comparamos las demás plataformas. En Black Engine construimos agentes con Claude conectados a tus sistemas; escríbenos por WhatsApp.