Tool Error Handling — 모델이 recover 하게

~22 min · tool-errors, recovery

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Tool 실패 시 agent crash 시키지 마. Exception 을 wrap — {error: 'rate-limited', detail: '...'} 를 tool 결과로 반환. 모델은 recover 잘해 — 다른 tool 시도, 사용자한테 묻기, gracefully abort.

Crash vs return 의 차이

Crash = agent 가 사용자한테 'something went wrong'. Return = 모델한테 fallback 기회. 같은 tool 실패가 두 path 에서 매우 다른 사용자 경험.

Secret leak 주의

Exception traceback 은 API key, internal hostname, query string 포함 가능. Strip 또는 summarize 후 모델한테 반환. Tool error = user-facing log 와 같은 위생.

Structured error shape

{error: '', message: '', detail: ''} 가 좋은 default. error class 는 모델 routing 에 도움 ('rate-limited' 면 wait, 'auth' 면 fallback tool, 'not-found' 면 사용자 confirm). Detail 은 디버깅용 — secrets 없이.

Code

Structured tool error 반환·python

for tc in tool_calls:
    try:
        func = TOOLS_MAP[tc.name]
        result = func(**json.loads(tc.arguments))
        output = json.dumps(result)
    except KeyError:
        output = json.dumps({"error": f"Unknown tool: {tc.name}"})
    except json.JSONDecodeError:
        output = json.dumps({"error": "Invalid JSON in tool arguments"})
    except TimeoutError:
        output = json.dumps({"error": f"Tool {tc.name} timed out"})
    except Exception as e:
        output = json.dumps({"error": str(e), "success": False})

    input_items.append({
        "type": "function_call_output",
        "call_id": tc.call_id,
        "output": output,  # always return JSON, even for errors
    })

External links

Tool error 패턴

Exercise

Tool loop 에서 tool handler 1 개에 일부러 exception raise. 두 전략 — (a) crash, (b) catch + {error,...} return. 각 case 의 assistant 후속 동작 비교.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousParallel Function Calling — 한 turn 에 여러 호출 Next →효과적인 Tool Description 설계

이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

🔔 답글 알림 (로그인 필요)

로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.