Tratamento de Erros e Recuperação

ChatFlowError (Base)
├── DependencyError (Dependências opcionais ausentes de canais)
├── ToolExecutionError (Erro não capturado durante a execução de ferramenta)
├── ToolSchemaError (Anotação de tipo de parâmetro inválida) [v0.4.0rc1]
├── AgentHandoffError (Destino de handoff desconhecido ou loop de transferências)
├── ProviderError (Erro de status de API de LLM, falha de rede ou timeout)
├── ReentrantTurnError (Invocação de turno concorrente em sessão bloqueada) [v0.4.0rc1]
└── SessionDeletedError (Mensagem despachada para uma sessão excluída) [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)

Início do Turno
    ├── Capturar Ponto de Controle: (history, active_agent, metadata)
    ├── Anexar Mensagem de Entrada do Usuário
    ├── Executar Turnos de LLM e Ferramentas
    │     ├── Sucesso: Confirmar resposta final do assistente no SessionStore
    │     └── Falha / CancelledError: Restaurar (history, active_agent, metadata)
    └── Liberar Bloqueio da Sessão

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:
        # O estado foi revertido automaticamente para antes do turno
        return "Our AI inference service is temporarily degraded. Please retry in a few moments."
    except TimeoutError:
        # Timeout do turno atingido; ponto de controle 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

# No v0.3.x, aplique timeouts de turno via 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,
)