Cómo crear un flujo de trabajo con agentes en Claude
Construye en Python un flujo multiagente con router, agente con herramientas y revisor automático usando la API de Claude.
- Python 3.10 o superior instalado
- Cuenta en la Claude Console con una API key activa y saldo o créditos
- Conocimientos básicos de Python: funciones, diccionarios y JSON
- Terminal y un editor de código (VS Code, PyCharm o similar)
- Diferenciar un flujo de trabajo con agentes de un simple prompt y cuándo usar cada patrón
- Crear un router que clasifica peticiones y decide qué rama del flujo ejecutar
- Programar un agente que usa herramientas (tool use) con un bucle controlado
- Implementar el patrón evaluador-optimizador para que un agente revise el trabajo de otro
- Añadir límites de iteraciones, trazas y salidas de emergencia para que el flujo no se descontrole
Preparar el entorno y la API key
Antes de escribir agentes, deja el entorno limpio. Crea una carpeta para el proyecto, un entorno virtual e instala el SDK oficial de Anthropic para Python. La API key la generas en la Claude Console, en la sección de claves de API, y la exportas como variable de entorno: el SDK la lee automáticamente de ANTHROPIC_API_KEY, así que nunca tienes que escribirla en el código. El caso que vamos a construir es real y muy común en tiendas online de España y LATAM: llega una consulta de un cliente, un agente la clasifica, otro consulta el estado del pedido con una herramienta, un tercero redacta la respuesta adaptada al país del cliente y un cuarto la revisa antes de enviarla. Son cuatro roles con responsabilidades separadas, que es justo lo que define un flujo de trabajo con agentes frente a un único prompt gigante. En Windows, usa el comando set o $env: en PowerShell en lugar de export.
mkdir flujo-agentes && cd flujo-agentes
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install anthropic
export ANTHROPIC_API_KEY='sk-ant-...' # PowerShell: $env:ANTHROPIC_API_KEY='sk-ant-...'
python -c "import anthropic; print(anthropic.__version__)"Crear la función base que llama a Claude
Todos los agentes del flujo comparten la misma forma de hablar con el modelo, así que encapsúlala en una función. Crea el archivo flujo.py con este contenido. La función ask recibe un system prompt (la 'personalidad' y las reglas del agente) y el mensaje del usuario, y devuelve solo el texto. Fíjate en que concatenamos los bloques de tipo text: la respuesta de la Messages API es una lista de bloques, no un string, y asumir resp.content[0].text funciona hasta el día en que el primer bloque no es texto. El modelo se lee de una variable de entorno con claude-opus-5-5 por defecto; así puedes probar el flujo con un modelo más barato para tareas sencillas (como clasificar) sin tocar código. Separar esta capa también te permite añadir más adelante reintentos, logging o medición de tokens en un único sitio en lugar de repetirlo en cada agente.
import os
import json
import anthropic
client = anthropic.Anthropic() # lee ANTHROPIC_API_KEY del entorno
MODEL = os.getenv('CLAUDE_MODEL', 'claude-opus-5-5')
def ask(system, user, max_tokens=1024):
resp = client.messages.create(
model=MODEL,
max_tokens=max_tokens,
system=system,
messages=[{'role': 'user', 'content': user}],
)
return ''.join(b.text for b in resp.content if b.type == 'text')
Construir el agente router que clasifica la consulta
El primer eslabón decide qué camino sigue la petición. Es el patrón routing: una llamada barata y rápida que clasifica la entrada y extrae datos estructurados (categoría, país y número de pedido). Pedimos JSON estricto en el system prompt y lo parseamos. Limpiamos posibles vallas de código markdown porque, aunque le digas 'solo JSON', a veces el modelo envuelve la salida en un bloque de código. Añade este código al final de flujo.py. El país es importante para el caso de uso: no es lo mismo responder a un cliente de Madrid que a uno de Buenos Aires o de Ciudad de México, y el router es quien captura ese dato para que el redactor lo use después. Si la categoría es 'otro', el flujo derivará a un humano en lugar de forzar una respuesta automática.
ROUTER_SYSTEM = """Eres un clasificador de consultas de clientes de una tienda online que vende en España y LATAM.
Devuelve SOLO un objeto JSON, sin texto adicional, con este formato:
{"categoria": "pedido" | "devolucion" | "otro", "pais": "código ISO de 2 letras o null", "pedido_id": "string o null"}
Deduce el país por la ciudad o el contexto si no se menciona explícitamente."""
def route(consulta):
raw = ask(ROUTER_SYSTEM, consulta, max_tokens=200).strip()
raw = raw.removeprefix('```json').removeprefix('```').removesuffix('```').strip()
try:
return json.loads(raw)
except json.JSONDecodeError:
return {'categoria': 'otro', 'pais': None, 'pedido_id': None}
Programar el agente de soporte con herramientas
Aquí está el corazón de un agente: el modelo decide cuándo llamar a una herramienta, tu código la ejecuta y le devuelves el resultado hasta que el modelo termina. Definimos la herramienta consultar_pedido con un input_schema en JSON Schema y simulamos la base de datos con un diccionario (en producción sería tu ERP, Shopify o la API de tu transportista). El bucle es el patrón estándar: si stop_reason es 'tool_use', añades la respuesta del asistente al historial, ejecutas cada bloque tool_use y devuelves un mensaje de usuario con los tool_result enlazados por tool_use_id. Cuando stop_reason deja de ser 'tool_use', el agente ha terminado y devuelves su texto. Este agente no redacta la respuesta final al cliente: solo reúne hechos. Separar 'investigar' de 'redactar' facilita que el revisor detecte invenciones después. Añade el bloque al final de flujo.py.
PEDIDOS = {
'A1001': {'estado': 'enviado', 'transportista': 'Correos', 'entrega_estimada': '18/11'},
'B2002': {'estado': 'en preparación', 'transportista': None, 'entrega_estimada': '20/11'},
}
TOOLS = [{
'name': 'consultar_pedido',
'description': 'Devuelve estado, transportista y fecha estimada de entrega de un pedido a partir de su ID.',
'input_schema': {
'type': 'object',
'properties': {'pedido_id': {'type': 'string', 'description': 'ID del pedido, por ejemplo A1001'}},
'required': ['pedido_id'],
},
}]
SOPORTE_SYSTEM = ('Eres un agente de soporte interno. Usa las herramientas para obtener datos reales del pedido. '
'Devuelve un resumen breve y factual de los hechos, sin redactar para el cliente. '
'Si no encuentras el pedido, dilo claramente.')
def run_tool(name, args):
if name == 'consultar_pedido':
data = PEDIDOS.get(args.get('pedido_id', ''), {'error': 'pedido no encontrado'})
return json.dumps(data, ensure_ascii=False)
return json.dumps({'error': f'herramienta desconocida: {name}'})
def agente_soporte(consulta, max_turnos=5):
messages = [{'role': 'user', 'content': consulta}]
for _ in range(max_turnos):
resp = client.messages.create(
model=MODEL, max_tokens=1024, system=SOPORTE_SYSTEM,
tools=TOOLS, messages=messages,
)
if resp.stop_reason != 'tool_use':
return ''.join(b.text for b in resp.content if b.type == 'text')
messages.append({'role': 'assistant', 'content': resp.content})
resultados = []
for b in resp.content:
if b.type == 'tool_use':
print(f'[tool] {b.name} {b.input}')
resultados.append({'type': 'tool_result', 'tool_use_id': b.id,
'content': run_tool(b.name, b.input)})
messages.append({'role': 'user', 'content': resultados})
raise RuntimeError('El agente superó el máximo de turnos')
Añadir el redactor y el revisor (evaluador-optimizador)
Ahora el patrón evaluador-optimizador: un agente genera y otro evalúa con criterios explícitos; si no aprueba, el primero reescribe con el feedback. El redactor adapta el registro al país detectado por el router: tuteo y euros en España, ustedes en México, voseo en Argentina, y español neutro si no hay país. El revisor recibe los HECHOS del agente de soporte y la RESPUESTA, y solo aprueba si no hay datos inventados. Pedirle una palabra exacta ('APROBADO') hace que la comprobación en código sea trivial y robusta. Este patrón brilla cuando tienes criterios de calidad claros y verificables; si los criterios son vagos ('que suene mejor'), el bucle puede dar vueltas sin converger. Añade este código al final de flujo.py.
TONOS = {
'ES': 'español de España, tuteando al cliente',
'MX': 'español de México, tratando al cliente de usted y usando ustedes en plural',
'AR': 'español rioplatense, con voseo',
'CO': 'español de Colombia, tratando al cliente de usted',
}
REVISOR_SYSTEM = ('Eres un revisor de calidad de atención al cliente. Compara la RESPUESTA con los HECHOS. '
'Si la respuesta es correcta, empática y no inventa ningún dato, responde exactamente: APROBADO. '
'Si no, lista los problemas en viñetas, sin reescribir la respuesta.')
def redactar(hechos, pais, feedback=''):
tono = TONOS.get(pais or '', 'español neutro latinoamericano')
sistema = (f'Eres redactor de atención al cliente. Escribe en {tono}. '
'Máximo 120 palabras. No inventes datos que no estén en los hechos.')
prompt = f'Hechos verificados:\n{hechos}'
if feedback:
prompt += f'\n\nCorrige la respuesta según este feedback del revisor:\n{feedback}'
return ask(sistema, prompt)
def revisar(hechos, respuesta):
return ask(REVISOR_SYSTEM, f'HECHOS:\n{hechos}\n\nRESPUESTA:\n{respuesta}', max_tokens=400)
Orquestar el flujo completo y ejecutarlo
Falta el orquestador que une todas las piezas: router, agente con herramientas, redactor y bucle de revisión con un máximo de iteraciones. Cada paso imprime una traza para que veas qué decide cada agente; en producción cambiarías los print por logging estructurado. Observa las salidas de emergencia: si la categoría es 'otro' se deriva a un humano, y si tras dos revisiones no hay aprobación también se escala en lugar de enviar algo dudoso. Esto es lo que convierte una demo en un flujo que puedes poner delante de clientes reales. Añade este bloque al final de flujo.py y ejecútalo con python flujo.py. Deberías ver la clasificación (categoría pedido, país MX, pedido B2002), la llamada a la herramienta, uno o dos veredictos del revisor y la respuesta final tratando al cliente de usted. Prueba después cambiando la consulta a un cliente de Madrid con el pedido A1001 y compara el tono.
def flujo(consulta, max_revisiones=2):
ruta = route(consulta)
print('[router]', ruta)
if ruta.get('categoria') == 'otro':
return 'ESCALADO: consulta derivada a un agente humano.'
hechos = agente_soporte(consulta)
print('[soporte]', hechos)
respuesta = redactar(hechos, ruta.get('pais'))
for i in range(max_revisiones):
veredicto = revisar(hechos, respuesta)
print(f'[revisor {i + 1}]', veredicto[:120])
if veredicto.strip().startswith('APROBADO'):
return respuesta
respuesta = redactar(hechos, ruta.get('pais'), feedback=veredicto)
return 'ESCALADO: la respuesta no superó la revisión.\n\n' + respuesta
if __name__ == '__main__':
consulta = 'Hola, escribo desde Ciudad de México. Mi pedido B2002 todavía no llega, ¿qué pasa?'
print('\n=== RESPUESTA FINAL ===\n' + flujo(consulta))
Has construido un flujo de trabajo con agentes de IA completo sobre la API de Claude: un router que clasifica y extrae datos, un agente que consulta pedidos mediante tool use con un bucle controlado, un redactor que adapta el tono al cliente de España o LATAM y un revisor que bloquea respuestas con datos inventados, todo con límites de iteración y escalado a humano. Ya dominas los patrones clave (routing, agente con herramientas y evaluador-optimizador) y puedes combinarlos para otros procesos como cualificación de leads, revisión de facturas o triaje de incidencias. El siguiente salto natural es conectar tus agentes a sistemas reales con MCP en lugar de diccionarios simulados, para que lean y escriban en tu CRM, tu ERP o tu base de datos de forma estándar y reutilizable.