Construye tu primer agente con Claude API y Python

Introducción

Los agentes de IA son sistemas que pueden razonar, planificar y ejecutar acciones de forma autónoma para completar objetivos complejos. Con la API de Claude de Anthropic y Python, puedes construir agentes sofisticados que usen herramientas externas, mantengan contexto de conversación y tomen decisiones iterativas. En este tutorial construiremos un agente completo desde cero.

Paso 1: Configurar el entorno de desarrollo

Crea un entorno virtual e instala las dependencias necesarias:

python -m venv agente-env
source agente-env/bin/activate  # En Windows: agente-env\Scripts\activate
pip install anthropic python-dotenv requests

Crea un archivo `.env` en la raíz del proyecto para almacenar tu API key de forma segura:

ANTHROPIC_API_KEY=sk-ant-tu-clave-aqui

Nunca incluyas claves de API directamente en el código fuente ni las subas a repositorios públicos.

Paso 2: Inicializar el cliente de Anthropic

Crea el archivo principal `agente.py` con la configuración base:

import os
import json
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY")) MODEL = "claude-opus-4-5" ```

El cliente de Anthropic maneja automáticamente la autenticación, reintentos con backoff exponencial y límites de velocidad.

Paso 3: Definir las herramientas del agente

Las herramientas son funciones que el agente puede invocar para interactuar con el mundo exterior. Define las herramientas usando el esquema JSON que espera la API:

tools = [
    {
        "name": "buscar_web",
        "description": "Busca información actualizada en internet sobre un tema",
        "input_schema": {
            "type": "object",
            "properties": {
                "consulta": {
                    "type": "string",
                    "description": "La consulta de búsqueda"
                }
            },
            "required": ["consulta"]
        }
    },
    {
        "name": "ejecutar_codigo",
        "description": "Ejecuta código Python y retorna el resultado",
        "input_schema": {
            "type": "object",
            "properties": {
                "codigo": {
                    "type": "string",
                    "description": "Código Python a ejecutar"
                }
            },
            "required": ["codigo"]
        }
    }
]

Paso 4: Implementar las funciones de las herramientas

Cada herramienta necesita una implementación real en Python:

import subprocess
import requests

def buscar_web(consulta: str) -> str: """Simula una búsqueda web (reemplaza con una API real como Serper o Brave)""" return f"Resultados de búsqueda para: {consulta}\n[Integra aquí tu API de búsqueda]"

def ejecutar_codigo(codigo: str) -> str: """Ejecuta código Python en un entorno aislado""" try: resultado = subprocess.run( ["python", "-c", codigo], capture_output=True, text=True, timeout=10 ) return resultado.stdout or resultado.stderr except subprocess.TimeoutExpired: return "Error: El código tardó demasiado en ejecutarse" except Exception as e: return f"Error: {str(e)}"

def ejecutar_herramienta(nombre: str, argumentos: dict) -> str: if nombre == "buscar_web": return buscar_web(argumentos["consulta"]) elif nombre == "ejecutar_codigo": return ejecutar_codigo(argumentos["codigo"]) return f"Herramienta desconocida: {nombre}" ```

Paso 5: Implementar el bucle de agente

El corazón del agente es un bucle que itera hasta que Claude decide que ha completado la tarea:

def ejecutar_agente(tarea: str, max_iteraciones: int = 10) -> str:
    mensajes = [{"role": "user", "content": tarea}]
    
    for iteracion in range(max_iteraciones):
        respuesta = client.messages.create(
            model=MODEL,
            max_tokens=4096,
            tools=tools,
            messages=mensajes
        )
        
        # Si Claude terminó, retorna la respuesta final
        if respuesta.stop_reason == "end_turn":
            return respuesta.content[0].text
        
        # Si Claude quiere usar una herramienta
        if respuesta.stop_reason == "tool_use":
            mensajes.append({"role": "assistant", "content": respuesta.content})
            resultados_herramientas = []
            
            for bloque in respuesta.content:
                if bloque.type == "tool_use":
                    resultado = ejecutar_herramienta(bloque.name, bloque.input)
                    resultados_herramientas.append({
                        "type": "tool_result",
                        "tool_use_id": bloque.id,
                        "content": resultado
                    })
            
            mensajes.append({"role": "user", "content": resultados_herramientas})
    
    return "El agente alcanzó el límite de iteraciones"

Paso 6: Añadir memoria de conversación

Para que el agente mantenga contexto entre sesiones, implementa persistencia de mensajes:

import json
from pathlib import Path

def guardar_historial(mensajes: list, archivo: str = "historial.json"): with open(archivo, "w", encoding="utf-8") as f: json.dump(mensajes, f, ensure_ascii=False, indent=2)

def cargar_historial(archivo: str = "historial.json") -> list: if Path(archivo).exists(): with open(archivo, "r", encoding="utf-8") as f: return json.load(f) return [] ```

Paso 7: Implementar sistema de prompts del sistema

Un buen prompt de sistema define la personalidad, capacidades y limitaciones del agente:

SISTEMA = """
Eres un asistente técnico experto. Tienes acceso a herramientas para buscar información
en internet y ejecutar código Python. Sigue este proceso:
1. Analiza la tarea del usuario
2. Planifica los pasos necesarios
3. Usa las herramientas disponibles cuando sea necesario
4. Verifica los resultados antes de responder
5. Proporciona respuestas claras y estructuradas

Siempre explica tu razonamiento antes de usar una herramienta. """ ```

Paso 8: Agregar manejo de errores y reintentos

import time
from anthropic import APIError, RateLimitError

def llamar_api_con_reintentos(mensajes, max_reintentos=3): for intento in range(max_reintentos): try: return client.messages.create( model=MODEL, max_tokens=4096, system=SISTEMA, tools=tools, messages=mensajes ) except RateLimitError: if intento < max_reintentos - 1: time.sleep(2 ** intento) # Backoff exponencial else: raise except APIError as e: print(f"Error de API: {e}") raise ```

Paso 9: Crear la interfaz de línea de comandos

def main():
    print("Agente Claude iniciado. Escribe 'salir' para terminar.")
    historial = cargar_historial()
    
    while True:
        tarea = input("\nTú: ").strip()
        if tarea.lower() == "salir":
            guardar_historial(historial)
            break
        
        historial.append({"role": "user", "content": tarea})
        print("\nAgente: ", end="", flush=True)
        
        respuesta = ejecutar_agente_con_historial(historial)
        print(respuesta)
        historial.append({"role": "assistant", "content": respuesta})

if __name__ == "__main__": main() ```

Paso 10: Pruebas y optimización

Prueba tu agente con casos de uso reales:

python agente.py

Escribe consultas como: "Calcula los primeros 20 números de Fibonacci y muéstralos en una tabla". El agente debería usar la herramienta `ejecutar_codigo` para calcularlos y formatear la respuesta.

Para optimizar el rendimiento, considera implementar caché de respuestas para consultas repetidas, streaming de respuestas para mejor UX, y logging detallado para depuración. Con estos 10 pasos tienes un agente completamente funcional listo para extender con nuevas herramientas según tus necesidades.