Gestión de Errores y Recuperación

ChatFlowError (Base)
├── DependencyError (Dependencias opcionales faltantes de canales)
├── ToolExecutionError (Error no controlado durante ejecución de herramienta)
├── ToolSchemaError (Anotación de tipo de parámetro inválida) [v0.4.0rc1]
├── AgentHandoffError (Destino de handoff desconocido o bucle de transferencias)
├── ProviderError (Error de estado HTTP de API de LLM, fallo de red o tiempo límite)
├── ReentrantTurnError (Invocación de turno concurrente en sesión bloqueada) [v0.4.0rc1]
└── SessionDeletedError (Mensaje despachado a una sesión eliminada) [v0.4.0rc1]

import logging
from chatflow_agent import Agent, Runner, tool

logger = logging.getLogger("app.tools")

@tool
def process_refund(order_id: str, amount: float) -> str:
    """Issue a refund for an order.

    Args:
        order_id: Order identifier formatted as ORD-XXXX.
        amount: Positive monetary value to refund.
    """
    if not order_id.startswith("ORD-"):
        raise ValueError("Invalid order format. Order ID must begin with 'ORD-'.")
    if amount <= 0:
        raise ValueError("Refund amount must be strictly greater than 0.")
    return f"Refund of ${amount:.2f} processed for order {order_id}."

agent = Agent(
    name="RefundBot",
    model="gpt-4o",
    tools=[process_refund],
    instructions="Process refunds accurately. If an order ID format is invalid, clarify with the user.",
)

runner = Runner(starting_agent=agent)

Inicio del Turno
    ├── Capturar Punto de Control: (history, active_agent, metadata)
    ├── Añadir Mensaje Entrante del Usuario
    ├── Ejecutar Turnos del LLM y Herramientas
    │     ├── Éxito: Confirmar respuesta final del asistente en SessionStore
    │     └── Fallo / CancelledError: Restaurar (history, active_agent, metadata)
    └── Liberar Bloqueo de Sesión

import asyncio
from chatflow_agent import Agent, Runner
from chatflow_agent.exceptions import ProviderError

def build_resilient_runner(agent: Agent) -> Runner:
    """Configure a runner with bounded handoffs and tool iterations."""
    return Runner(
        starting_agent=agent,
        max_tool_iterations=6,
        max_handoffs_per_turn=3,
    )

async def execute_turn_with_recovery(
    runner: Runner,
    session_id: str,
    user_message: str,
) -> str:
    """Execute a turn with explicit exception handling and graceful fallback."""
    try:
        response = await runner.run_async(
            session_id=session_id,
            user_message=user_message,
        )
        return response.content
    except ProviderError as err:
        # El estado fue revertido automáticamente al estado previo al turno
        return "Our AI inference service is temporarily degraded. Please retry in a few moments."
    except TimeoutError:
        # Tiempo límite del turno excedido; punto de control restaurado
        return "The request took too long to complete. Please try a simpler question."
    except Exception as err:
        return "An unexpected system error occurred. Our operations team has been notified."

# [no-exec: illustrative turn timeout call]
import asyncio

# En v0.3.x, aplica tiempos límite de turno mediante asyncio.wait_for
response = await asyncio.wait_for(
    runner.run_async(
        session_id="customer-1029",
        user_message="Analyze this quarterly financial audit report...",
    ),
    timeout=45.0,
)