day4_practice/tools_basic.py · tool_error.py

도구 설계 플레이어: 모델이 읽는 것은 설명서뿐

@tool 을 세 단계 깊이로 쓸 때 모델에게 실제로 전달되는 도구 정보(이름, 설명, 입력 JSON 스키마)가 어떻게 달라지는지, 그리고 실패를 예외 대신 문자열로 돌려주면 무엇이 달라지는지를 한 단계씩 넘겨 봅니다. 두 파일은 모델을 부르지 않으므로 화면의 출력과 스키마는 모두 실제로 실행해 얻은 값입니다.

한눈에 보는 구조

① 파이썬 코드에 쓰는 것 이름 함수 이름 · @tool("이름") 설명 docstring · description= 입력 스키마 타입 힌트 · args_schema= 함수 본문 모델에게는 가지 않음 ② 도구 객체 StructuredTool .name 모델이 부를 이름 .description 언제 쓰는지 적은 글 .args_schema 인자 규칙 (Pydantic 모델) .func 실행할 함수 본문 ③ bind_tools 가 싣는 toolSpec name description inputSchema.json 본문과 반환 타입은 실리지 않음 모델: 설명서만 보고 도구를 고름 tool_calls ④ 실행: tool.invoke(인자) args_schema 검증 → 함수 본문 → 반환값 Agent 안에서는 ToolMessage.content

모델이 도구에 대해 아는 것은 ③의 세 칸뿐이고, 도구를 부른 뒤 아는 것은 ④가 돌려준 값뿐입니다. 초록 점선은 입력 스키마가 ③으로 안내문이 되는 동시에 ④에서 검문소로 한 번 더 쓰인다는 뜻입니다. 플레이어의 단계마다 해당하는 칸이 파랗게 표시됩니다.

이 단계에서 일어나는 일

네 가지 정의를 나란히

플레이어에서 본 네 도구가 모델에게 보내는 정보를 한 표로 모았습니다. 마지막 열은 tool_error.py 의 같은 이름 도구입니다.

단계 1 add단계 2 calculator단계 3 search_employeetool_error.py search_employee
이름의 출처함수 이름데코레이터 첫 인자 (함수 이름은 _internal_calc)함수 이름함수 이름
설명의 출처docstring 한 줄description= 인자docstring 네 줄docstring 전체 (Args:, Returns: 포함)
입력 스키마의 출처타입 힌트타입 힌트args_schema=SearchEmployeeInput타입 힌트
인자별 설명없음없음description 칸에 있음없음 (설명 글 안에만 있음)
"2자 이상" 규칙--스키마의 minLength: 2설명 글의 "(최소 2자)"
규칙을 어기면--본문 전에 ValidationError 예외본문의 if 가 안내 문자열을 반환

함정과 주의

관련 파일