Módulo 13: Agentes con la API

Agentes con la API: tool use, streaming y batch

La API te da control total sobre la IA. Puedes crear agentes que usan herramientas, toman decisiones, procesan miles de documentos, y se integran con tu software. No es un chat: es un sistema programable.

Tool use

Le defines herramientas al modelo con un JSON Schema. El modelo decide cuándo usarlas:

tools = [{
    "name": "buscar_cliente",
    "description": "Busca un cliente por nombre o email",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Nombre o email"}
        },
        "required": ["query"]
    }
}]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Busca a Pedro García"}]
)

Streaming

Respuestas token a token para UX instantánea:

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resumen ejecutivo"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Batch API (50% descuento)

Procesamiento masivo: 500 documentos, 1000 emails. Envías todo de golpe, resultados en menos de 24h:

batch = client.batches.create(requests=[
    {"custom_id": f"doc-{i}", "params": {
        "model": "claude-sonnet-4-20250514",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": f"Clasifica: {doc}"}]
    }} for i, doc in enumerate(documentos)
])

Agent loop completo

def agent_loop(user_message):
    messages = [{"role": "user", "content": user_message}]
    while True:
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=2048, tools=tools, messages=messages)
        tool_blocks = [b for b in response.content if b.type == "tool_use"]
        if not tool_blocks:
            return response.content[0].text
        messages.append({"role": "assistant", "content": response.content})
        results = [{"type": "tool_result", "tool_use_id": b.id,
            "content": json.dumps(execute_tool(b.name, b.input))}
            for b in tool_blocks]
        messages.append({"role": "user", "content": results})