AI Agents · Aula

Detectando e recuperando-se de erros de ferramentas

Quando uma ferramenta retornar erro 500, devolva o erro ao modelo para que ele tente uma abordagem diferente em vez de falhar.

Detectando e recuperando-se de erros de ferramentas é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

As ferramentas falham. Prepare-se.

Toda ferramenta real falha às vezes:

Tempos limite de rede
Limites de taxa
Argumentos inválidos fornecidos pelo modelo
Indisponibilidade de serviços externos
Autenticação inválida

Os agentes em produção precisam se recuperar de forma adequada.

Sempre retorne, nunca lance exceções

Dentro do ciclo do agente, capture todos os erros das ferramentas e retorne-os como conteúdo. Nunca permita que uma exceção encerre o ciclo:

def safe_dispatch(tool_call):
    try:
        args = json.loads(tool_call.function.arguments)
        return TOOLS[tool_call.function.name](**args)
    except json.JSONDecodeError:
        return {'error': 'Arguments are not valid JSON.'}
    except KeyError:
        return {'error': f'Unknown tool: {tool_call.function.name}'}
    except Exception as e:
        return {'error': f'{type(e).__name__}: {e}'}

Formato estruturado de erro

Use um formato consistente para que o modelo reconheça os erros:

error = {'ok': False, 'error_type': 'TimeoutError', 'error_message': 'Tavily timed out after 10s', 'retryable': True}
print(error)

Diferencie erros que permitem nova tentativa dos permanentes

Alguns erros justificam uma nova tentativa (tempo limite); outros não (404). Informe ao modelo:

if isinstance(e, requests.Timeout):
    return {'ok': False, 'retryable': True, 'error': str(e)}
if isinstance(e, ValueError):
    return {'ok': False, 'retryable': False, 'error': str(e)}

Tente novamente automaticamente em erros transitórios

Para chamadas de rede, tente novamente usando uma espera exponencial crescente:

from tenacity import retry, wait_exponential, stop_after_attempt, retry_if_exception_type

@retry(
    wait=wait_exponential(multiplier=1, max=10),
    stop=stop_after_attempt(3),
    retry=retry_if_exception_type((requests.Timeout, requests.ConnectionError))
)
def web_search(query):
    return requests.get('https://api.tavily.com/search', ...).json()

Validação de argumentos

Antes de chamar a ferramenta, valide os argumentos com um modelo do Pydantic:

from pydantic import BaseModel, ValidationError

class SearchArgs(BaseModel):
    query: str
    k: int = 5

try:
    args = SearchArgs.model_validate_json(tool_call.function.arguments)
except ValidationError as e:
    return {'error': f'Bad arguments: {e}'}

Mostre o erro ao modelo

Acrescente o erro como resultado de uma ferramenta e chame o modelo novamente. Muitas vezes, o modelo corrige a si próprio:

messages.append({
    'role': 'tool',
    'tool_call_id': tc.id,
    'content': json.dumps({'error': 'Argument k must be an integer'})
})
# Next model call: 'Sorry, let me retry with k=5...'

Evite ciclos infinitos de erro

Alguns modelos, quando recebem um erro, repetem a mesma chamada problemática. Limite o ciclo e detecte repetições:

recent_calls = []
for tc in msg.tool_calls:
    key = (tc.function.name, tc.function.arguments)
    if recent_calls.count(key) >= 3:
        return 'Agent stuck in retry loop, aborting.'
    recent_calls.append(key)

Recuperação específica da ferramenta

Para ferramentas reconhecidamente instáveis, crie a lógica de novas tentativas INSIDE da ferramenta, não no loop:

def search_with_fallback(query):
    try:
        return tavily_search(query)
    except Exception:
        return bing_search(query)   # secondary provider

Tempo limite em todas as chamadas

Toda chamada externa precisa de um tempo limite. Caso contrário, um serviço lento congela todo o seu agente:

import requests
response = requests.get(url, timeout=10)  # 10s

# For LLM calls:
from openai import OpenAI
client = OpenAI(timeout=30.0)

Disjuntores de circuito

Quando uma ferramenta falha repetidamente, "abra" o circuito e ignore-a por algum tempo:

import time

class CircuitOpen(Exception):
    pass

def circuit(failure_threshold=5, recovery_timeout=60):
    def decorator(func):
        state = {'failures': 0, 'open_until': 0}
        def wrapper(*args, **kwargs):
            if time.time() < state['open_until']:
                raise CircuitOpen('circuit is open')
            try:
                result = func(*args, **kwargs)
                state['failures'] = 0
                return result
            except Exception:
                state['failures'] += 1
                if state['failures'] >= failure_threshold:
                    state['open_until'] = time.time() + recovery_timeout
                raise
        return wrapper
    return decorator

@circuit(failure_threshold=3, recovery_timeout=1)
def fragile_tool(x):
    if x < 0:
        raise ValueError('bad input')
    return x * 2

for x in [1, -1, -1, -1, -1]:
    try:
        print('ok', fragile_tool(x))
    except CircuitOpen as e:
        print('blocked:', e)
    except ValueError as e:
        print('failed:', e)

Registrando erros com contexto

Registre informações suficientes para depurar o problema posteriormente: nome da ferramenta, argumentos, tipo de erro, rastreamento da pilha, ID da requisição, ID do usuário e ID do rastreamento. Envie tudo para sua ferramenta de observabilidade.

Degradação controlada

Quando uma ferramenta crítica estiver indisponível, informe isso honestamente ao usuário em vez de fingir que o agente teve êxito:

if all_search_tools_failed:
    return 'I was unable to search the web right now. Please try again in a few minutes.'

Padrão para erros de ferramentas

Qual é a forma mais segura de lidar com exceções de ferramentas dentro do loop do agente?

Recapitulação

As ferramentas falham. Capture, classifique, estruture como conteúdo e permita que o agente se recupere. Adicione tempos limite, novas tentativas e disjuntores de circuito para obter confiabilidade em produção.

Perguntas Frequentes

A aula “Detectando e recuperando-se de erros de ferramentas” é grátis?

Sim — o texto completo de “Detectando e recuperando-se de erros de ferramentas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Detectando e recuperando-se de erros de ferramentas”?

Quando uma ferramenta retornar erro 500, devolva o erro ao modelo para que ele tente uma abordagem diferente em vez de falhar. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Detectando e recuperando-se de erros de ferramentas”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

ReAct: padrão raciocinar + agir
Implementando ReAct do zero
Conjuntos comuns de ferramentas (Web, calculadora, RAG)
Detectando e recuperando-se de erros de ferramentas

← Voltar para AI Agents