Turnos, mensajes y resultados: anatomía de una sesión

Los mensajes que recibes

Cuando iteras sobre query(), el SDK te entrega objetos que distingues con isinstance():

Mensaje	Cuándo llega
SystemMessage	Eventos de sesión: init, compact_boundary (se resumió el historial)…
AssistantMessage	Cada respuesta de Claude: texto o llamadas a herramientas
UserMessage	Los resultados de las herramientas que vuelven a Claude
StreamEvent	Solo si activas include_partial_messages
ResultMessage	El final: texto, costo, tokens, turnos e id de sesión

El ResultMessage

Su campo subtype te dice cómo terminó el loop:

• success: terminó bien; solo este trae result con el texto final.
• error_max_turns: se alcanzó max_turns.
• error_max_budget_usd: se alcanzó el presupuesto.
• error_during_execution: hubo un error durante la ejecución.

Todos traen total_cost_usd, usage, num_turns y session_id. La documentación advierte que en una llamada simple a query() el SDK lanza una excepción después de emitir un resultado de error, así que envuelve el bucle en try.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def run(prompt: str, opts: ClaudeAgentOptions):
    try:
        async for msg in query(prompt=prompt, options=opts):
            if isinstance(msg, ResultMessage):
                print(msg.subtype, msg.num_turns, msg.total_cost_usd)
                if msg.subtype == "success":
                    return msg.result
    except Exception as err:
        print(f"La sesión terminó con error: {err}")

Fuentes: agent loop y referencia del SDK de Python.