AI 서비스 엔지니어링: Track A
5주차 · API 해부와 tool calling
CodeCompose · 2026-08-21
② 도구가 있으면
같은 뇌인데 고리가 바깥까지 뻗습니다
flowchart TB
subgraph S["AI 서비스 (제품)"]
direction TB
UI["대화 화면"] --> M["AI 모델 · 뇌<br/>텍스트 → 텍스트"]
M -->|"① 실행 요청"| H["하네스<br/>권한·검증·한도"]
H -->|"② 통과한 것만"| T["도구<br/>검색·파일·계산·예약"]
T -->|"④ 관찰 결과"| M
end
T -->|"③ 바깥과 닿는<br/>유일한 통로"| W["바깥 세상<br/>웹·DB·파일·시계"]
W --> T바뀐 것은 모델이 아니라 모델이 부를 수 있는 것이 생겼다는 점뿐입니다.
1. 최소 호출
01_hello_completion.py · 요청·응답 JSON 원문을 그대로 본다
- 코드
request = {
"model": model,
"messages": [{"role": "user", "content": "안녕하세요! 한 문장으로 인사해 주세요."}],
}
response = completion(**request)
print(response.model_dump_json(indent=2))- 실행
docker compose exec lab python examples/01_api/01_hello_completion.py 응답 원문: 모델이 돌려주는 것 전체
{
"model": "gemini-3.5-flash-lite",
"choices": [
{
"finish_reason": "stop",
"message": {
"content": "안녕하세요! 만나서 반가운데, 오늘 어떤 도움이 필요하신가요?",
"role": "assistant",
"tool_calls": null,
"provider_specific_fields": { "thought_signatures": ["El4KXAERTTIP…"] }
}
}
],
"usage": { "completion_tokens": 16, "prompt_tokens": 11, "total_tokens": 27 }
} 2. 역할: system이 내용과 형식을 정한다
02_roles.py · 같은 질문에 system만 갈아 끼운다
personas = {
"(system 없음)": None,
"미슐랭 심사위원": "당신은 미슐랭 심사위원입니다. 미식가의 기준으로 …",
"초등학생 눈높이": "당신은 초등학생에게 설명하는 선생님입니다. …",
"JSON 응답기": "반드시 {\"추천\": ..., \"이유\": ...} 형태의 JSON으로만 …",
}질문은 하나로 고정: “오사카에서 꼭 먹어야 할 것 하나만”
docker compose exec lab python examples/01_api/02_roles.py 3. 토큰: 한글이 더 비싼 이유
03_tokens.py · API 호출 없이 토크나이저만으로 돈다. 키 불필요
- 실행
docker compose exec lab python examples/01_api/03_tokens.py- 결과
한국어 | 영어 | 문장
11 | 9 | 안녕하세요, 오늘 날씨가 정말 좋네요.…
23 | 23 | 3박 4일 오사카 여행 일정을 짜 주세요. 예산은 80…
19 | 10 | 대규모 언어 모델은 토큰 단위로 텍스트를 처리합니다.…
합계: 한국어 53 토큰 vs 영어 42 토큰 (약 1.3배)과금과 컨텍스트 한도는 글자 수가 아니라 토큰 수 기준입니다.
세 번째 문장(19 vs 10)처럼 2배 가까이 벌어지기도 합니다.
4. 컨텍스트 한도: 넘치면 잘리는 게 아니라 거부된다
04_context_limit.py · 한도가 가장 작은 모델에 한도의 1.5배를 보낸다
- 코드
model = min(available_models(), key=lambda m: get_model_info(m)["max_input_tokens"])
limit = get_model_info(model)["max_input_tokens"]
text = chunk * (int(limit * 1.5) // chunk_tokens + 1) # 확실히 초과- 실행
docker compose exec lab python examples/01_api/04_context_limit.py요청이 거부되므로 과금되지 않습니다.
5. temperature: 재현성과 다양성의 손잡이
05_temperature.py · 같은 질문을 0과 1로 5번씩
- 실행
docker compose exec lab python examples/01_api/05_temperature.py- 결과
(시연 모델: openai/gpt-5.4-nano)
=== temperature = 0.0 ===
1회: 도쿄 / 2회: 도쿄 / 3회: 도쿄 / 4회: 도쿄 / 5회: 도쿄
→ 서로 다른 답 1종
=== temperature = 1.0 ===
1회: **도쿄** / 2회: 도쿄 / 3회: 도쿄 / 4회: **오사카** / 5회: 도쿄 (Tokyo)
→ 서로 다른 답 4종 6. 스트리밍: 답은 조각으로 온다
06_streaming.py · 채팅 UI가 글자를 흘리는 것의 실체
- 실행
docker compose exec lab python examples/01_api/06_streaming.py- 결과
=== 처음 5개 청크 원문 ===
chunk[0] delta='**'
chunk[1] delta='"먹다 지쳐 쓰러진다는 \'구이도락(食い'
chunk[2] delta="倒れ)'의 본고장이자, 화려한 네온사인과 정겨운 인간미가 공존"
chunk[3] delta='하는 일본 최고의 활기찬 도시."**'
chunk[4] delta=''조각의 크기와 경계는 프로바이더 마음입니다.
청크 0은 ** 두 글자, 청크 2는 한 구절. 이어붙이는 쪽이 완성 텍스트를 책임집니다.
7. 병렬 호출: 동시에 물으면 몇 배 빠른가
07_async_parallel.py · 도시 5곳을 순차로, 그리고 동시에
- 코드
tasks = [acompletion(model=model, messages=[…]) for city in cities]
await asyncio.gather(*tasks)- 실행
docker compose exec lab python examples/01_api/07_async_parallel.py- 결과
=== 순차 호출 (5회) === 5.2초
=== 병렬 호출 (5회 동시) === 1.5초
=== 비교 === 순차 5.2초 → 병렬 1.5초 (약 3.4배)LLM 호출은 네트워크 대기가 대부분이라 병렬화 이득이 큽니다.
acompletion + gather 패턴 하나면 충분하고,
여러 곳을 동시에 물어보는 에이전트가 이 패턴의 확장판입니다.
8. 무상태: 기억은 서버가 아니라 배열에 있다
08_multiturn_stateless.py · 히스토리 없이, 그리고 실어서
- 실행
docker compose exec lab python examples/01_api/08_multiturn_stateless.py- 결과
=== 1턴: 자기소개 ===
김철수님, 안녕하세요! 오사카 여행 계획을 세우고 계시다니 …
=== 2턴 (히스토리 없이): 제 이름이 뭐라고 했죠? ===
죄송하지만, 이전 대화에서 이름을 말씀해 주지 않으셔서 저는 아직
성함을 모릅니다.
=== 2턴 (히스토리 포함): 같은 질문 ===
철수님의 이름은 김철수님이십니다! compact가 배열을 바꾸는 모양
flowchart LR
subgraph BEFORE["compact 전 — 한도에 접근"]
direction TB
A1["system<br/>역할·규칙 (+ 저장된 메모리)"]
A2["오래된 원문 왕복 1~48<br/>(수만 토큰)"]
A3["최근 원문 왕복 49~50"]
A4["user: 방금 보낸 메시지"]
A1 --> A2 --> A3 --> A4
end
subgraph AFTER["compact 후 — 다음 요청의 배열"]
direction TB
B1["system<br/>그대로 유지"]
B2["요약 메시지 1개<br/>'지금까지: 오사카 3박4일 확정,<br/>예산 80만원, 숙소는 난바…'"]
B3["최근 원문 왕복 49~50<br/>원문 그대로 유지"]
B4["user: 방금 보낸 메시지"]
B1 --> B2 --> B3 --> B4
end
BEFORE -->|"오래된 구간을<br/>LLM으로 요약"| AFTER10. JSON 강제: 부탁이 아니라 계약으로
09_json_mode.py · 부탁한 버전과 강제한 버전을 json.loads에 통과시킨다
- 실행
docker compose exec lab python examples/01_api/09_json_mode.py- 결과
=== 그냥 부탁만 한 경우 ===
오사카의 대표적인 명소 2곳을 담은 JSON 배열입니다.
```json
[ { "name": "오사카 성", … } ]
```
→ json.loads 실패: Expecting value: line 1 column 1 (char 0)
=== response_format으로 강제한 경우 ===
[{"name": "오사카 성", "fee": "600엔"}, {"name": "우메다 스카이 빌딩", …}]
→ json.loads 통과 11. 이미지 입력: 멀티모달도 같은 구조
10_vision.py · 이미지를 직접 받아 base64 data URL로 싣는다
- 코드
req = urllib.request.Request(image_url, headers={"User-Agent": "week05-agent-lab/1.0"})
image_b64 = base64.b64encode(urllib.request.urlopen(req).read()).decode()
content = [
{"type": "text", "text": "이 사진의 건물이 무엇인지 한 문장으로 답해 주세요."},
{"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b64}"}},
]- 실행
docker compose exec lab python examples/01_api/10_vision.py- 결과
=== 응답 ===
이 사진 속 주요 건물은 일본 오사카에 위치한 역사적인 랜드마크인 오사카성입니다. 12. 비용 계산: 토큰 곱하기 단가
11_cost_calc.py · 키 없이 돈다
- 실행
docker compose exec lab python examples/01_api/11_cost_calc.py- 결과
=== 모델별 비용 (litellm 내장 단가표) ===
모델 입력단가/1M 출력단가/1M 이 호출
gemini/gemini-3.5-flash-lite $ 0.30 $ 2.50 $ 0.001257
openai/gpt-5.4-nano $ 0.20 $ 1.25 $ 0.000630
anthropic/claude-haiku-4-5 $ 1.00 $ 5.00 $ 0.002523비용 = 입력 토큰 × 입력 단가 + 출력 토큰 × 출력 단가
같은 일을 세 가지 문법으로
# 세 회사의 공식 SDK
openai.OpenAI().chat.completions.create(model="gpt-5.4-nano", messages=[…])
genai.Client().models.generate_content(model="gemini-3.5-flash-lite", contents="…")
anthropic.Anthropic().messages.create(model="claude-haiku-4-5", max_tokens=1024, …)
# LiteLLM — 셋 다 이 한 줄. 바뀌는 것은 model 문자열뿐
litellm.completion(model="<프로바이더/모델>", messages=[…])공식 SDK로 3사를 지원하려면 호출부 세 벌, 응답 파싱 세 벌, 에러 처리 세 벌. LiteLLM은 그 셋을 OpenAI 호환 형태 하나로 통일합니다.
2. 프로바이더 교체는 문자열 한 줄
01_provider_swap.py · 호출 코드는 한 글자도 바뀌지 않는다
- 코드
for model in available_models(): # 키가 채워진 프로바이더들
answer = completion(
model=model, messages=[{"role": "user", "content": question}]
).choices[0].message.content- 실행
docker compose exec lab python examples/02_litellm/01_provider_swap.py- 결과
=== gemini/gemini-3.5-flash-lite ===
저는 구글(Google)에서 개발한 대규모 언어 모델, 제미나이(Gemini)입니다.
=== openai/gpt-5.4-nano ===
저는 OpenAI의 ChatGPT(대화형 AI) 모델입니다.
=== anthropic/claude-haiku-4-5 ===
저는 Anthropic이 만든 Claude라는 AI 어시스턴트입니다. 3. 3사 비교: 응답·지연·비용을 나란히
02_three_way_compare.py · “어느 모델을 쓸까”는 감이 아니라 측정의 문제
- 실행
docker compose exec lab python examples/02_litellm/02_three_way_compare.py- 결과
=== 비교 표 ===
모델 지연 입력tk 출력tk 비용
gemini/gemini-3.5-flash-lite 1.5s 24 90 $ 0.000232
openai/gpt-5.4-nano 1.7s 30 120 $ 0.000156
anthropic/claude-haiku-4-5 2.3s 43 124 $ 0.000663같은 프롬프트인데 입력 토큰부터 다릅니다.
프로바이더마다 토크나이저와 내부 포장이 다르기 때문입니다.
품질은 눈으로, 지연과 비용은 숫자로 비교합니다.
4. 폴백: 주 모델이 죽으면 이어받는다
03_fallback.py · 존재하지 않는 모델을 1순위로 둔다
- 코드
resp = completion(
model="openai/gpt-없는-모델", # 반드시 실패하는 1순위
messages=[…],
fallbacks=["gemini/gemini-3.5-flash-lite"],
)- 실행
docker compose exec lab python examples/02_litellm/03_fallback.py- 결과
LiteLLM:ERROR: … Fallback attempt failed for model openai/gpt-없는-모델:
litellm.BadRequestError: OpenAIException - invalid model ID
=== 결과 ===
실제 응답한 모델: gemini-3.5-flash-lite
답: 폴백 성공 5. 재시도와 타임아웃: 순간 장애의 방어
04_retry_timeout.py · 불가능한 타임아웃 0.001초로 에러를 재현
- 실행
docker compose exec lab python examples/02_litellm/04_retry_timeout.py- 결과
=== 타임아웃 재현 (timeout=0.001초) ===
litellm.Timeout: Connection timed out …
=== 정상 설정 (timeout=30초, num_retries=2) ===
답: 2
실패하면 최대 2회까지 자동으로 다시 시도한 뒤에야 에러를 낸다timeout: 이 시간 안에 답이 없으면 끊는다.num_retries: 끊기면 몇 번 다시
8. rate limit: 백오프로 살아남기
07_rate_limit.py · 429를 만나면 1초 → 2초 → 4초 기다렸다 재시도
- 실행
docker compose exec lab python examples/02_litellm/07_rate_limit.py- 결과
=== 연속 15회 빠른 호출 (한도를 만나러 간다) ===
1회 성공 … 15회 성공
=== 정리 ===
한도는 장애가 아니라 일상이다. 백오프는 에이전트 루프의 기본 장비다.이번 실측은 유료 티어라 한도에 닿지 않았고, 백오프 코드는 할 일 없이
통과했습니다.
무료 티어에서는 429! 1초 백오프 후 재시도 줄이 등장합니다.
걸리든 안 걸리든 코드는 같아야 한다는 것이 요점입니다.
6. 캐싱: 같은 질문 두 번째는 공짜·즉시
05_cache.py · 인메모리 캐시를 켜고 같은 요청을 두 번
- 코드
litellm.cache = Cache(type="local") # 프로세스 안 인메모리 캐시
r1 = completion(model=model, messages=messages, caching=True)
r2 = completion(model=model, messages=messages, caching=True) # 캐시에서- 실행
docker compose exec lab python examples/02_litellm/05_cache.py- 결과
=== 1회차 (API까지 다녀옴) === 2.09초
=== 2회차 (같은 요청) === 0.002초
=== 비교 === 2.09초 → 0.002초. 같은 답인가: True 7. 비용 콜백: 호출마다 장부에 쌓인다
06_cost_callback.py · 호출부에는 한 줄도 손대지 않는다
- 코드
def track_cost(kwargs, completion_response, start_time, end_time):
ledger["calls"] += 1
ledger["cost"] += kwargs.get("response_cost") or 0.0
litellm.success_callback = [track_cost]- 실행
docker compose exec lab python examples/02_litellm/06_cost_callback.py- 결과
호출: '1+1은?' / '오사카는 어느 나라?' / '라멘 한 그릇 평균 가격은?'
=== 장부 ===
호출 3건, 누적 비용 $0.000870 9. 라우터: 별명 하나 뒤에 배포 여러 개
08_router.py · 실모델 여러 개를 travel-llm 하나로 묶는다
- 코드
deployments = [
{"model_name": "travel-llm", "litellm_params": {"model": m}}
for m in available_models()
]
router = Router(model_list=deployments, routing_strategy="simple-shuffle")
resp = router.completion(model="travel-llm", messages=[…])- 실행
docker compose exec lab python examples/02_litellm/08_router.py 요청 6건이 3사에 흩어진다
=== 배포 3개에 요청 6건 분산 ===
요청 1 → 처리한 모델: claude-haiku-4-5-20251001
요청 2 → 처리한 모델: gpt-5.4-nano-2026-03-17
요청 3 → 처리한 모델: gpt-5.4-nano-2026-03-17
요청 4 → 처리한 모델: claude-haiku-4-5-20251001
요청 5 → 처리한 모델: claude-haiku-4-5-20251001
요청 6 → 처리한 모델: gemini-3.5-flash-lite호출부는 travel-llm이라는 별명 하나만 압니다.
쉬운 질문은 싼 모델로, 어려운 질문은 좋은 모델로 나누는 배정이
이 구조 위에 섭니다.
10. 모델 메타데이터: 한도와 단가를 코드로 읽는다
09_model_info.py · 키 없이 돈다
- 실행
docker compose exec lab python examples/02_litellm/09_model_info.py- 결과
=== 이 랩이 쓰는 모델들 ===
모델 입력한도 출력한도 입력$/1M 출력$/1M
gemini/gemini-3.5-flash-lite 1,048,576 65,536 0.30 2.50
openai/gpt-5.4-nano 272,000 128,000 0.20 1.25
anthropic/claude-haiku-4-5 200,000 64,000 1.00 5.00
gemini/gemini-embedding-001 2,048 0 0.15 0.00“이 입력이 들어가는가”와 “이 호출은 얼마인가”를 실행 전에 코드가 판단합니다.
4장의 한도 초과 예제가 입력한도 열을,
6주차의 사전 비용 추정이 단가 열을 읽습니다.
11. 임베딩: 같은 인터페이스의 다른 출구
10_embedding.py · completion은 문장을, embedding은 숫자 벡터를
- 실행
docker compose exec lab python examples/02_litellm/10_embedding.py- 결과
=== 벡터의 모양 ===
문장 1개 → 3072차원 벡터
앞 6개 값: [0.0116, -0.004, 0.0088, -0.0772, -0.0033, -0.0068]
=== 코사인 유사도 ===
'국물 요리' vs '탕이나 찌개' = 0.843 (의미가 가깝다)
'국물 요리' vs '주가 상승' = 0.599 (멀다)단어가 하나도 겹치지 않는 “든든한 국물 요리”와 “뜨끈한 탕이나 찌개”가
0.843으로 가깝게 잡혔습니다.
4주차의 의미 검색이 바로 이 벡터 위에 섰습니다.
1. 환율 도구 하나짜리 최소 구성
01_single_tool.py
- 코드
def get_exchange_rate(currency: str) -> dict:
return {"currency": currency, "krw": RATES[currency]}
resp = completion(model=model, messages=messages, tools=tools)
call = resp.choices[0].message.tool_calls[0] # ① 모델의 실행 요청
result = get_exchange_rate(**json.loads(call.function.arguments)) # ② 우리가 실행
messages.append({"role": "tool", "tool_call_id": call.id,
"content": json.dumps(result)}) # ③ 결과 회신- 실행
docker compose exec lab python examples/03_tools/01_single_tool.py 세 줄로 요약하면
call = resp.choices[0].message.tool_calls[0] # ① 모델이 요청했다
result = 우리_함수(**json.loads(call.function.arguments)) # ② 우리가 실행했다
messages.append({"role": "tool", "tool_call_id": call.id, …}) # ③ 우리가 되돌려줬다call.id를 그대로 돌려주는 이유: 한 턴에 도구 요청이 여러 개 올 수 있어서, 어느 요청에 대한 결과인지 짝을 맞춰야 합니다.arguments가 dict가 아니라 문자열인 것도 봐 두세요. JSON 문자열이므로json.loads가 필요합니다.
2. tool call의 실체: 메시지 필드 하나
02_roundtrip_raw.py · 같은 왕복을 원문으로
- 실행
docker compose exec lab python examples/03_tools/02_roundtrip_raw.py- 결과
=== ① 모델이 보낸 assistant 메시지 원문 ===
{
"content": null,
"role": "assistant",
"tool_calls": [
{
"function": { "arguments": "{\"city\": \"오사카\"}", "name": "get_weather" },
"id": "call_85312__thought__El4KXAER…",
"type": "function"
}
]
} 이 시점의 messages 배열
=== ③ 이 시점의 messages 배열 전체 구조 ===
[0] role=user content
[1] role=assistant tool_calls
[2] role=tool content
=== ④ 최종 답 ===
오사카의 오늘 날씨는 맑고, 기온은 21도입니다. 야외활동하기 좋은 날씨네요!content는null이고, 우리가 돌려주는 것도 role이 tool인 평범한 메시지- Gemini는 call id에 자기 내부 서명을 붙여 보냅니다. 원문에서만 보입니다.
- 프로바이더마다 다른 이 결을 담요처럼 덮는 것이 LiteLLM의 일입니다.
도구가 메우는 세 가지 구멍
flowchart TD
M["모델<br/>텍스트 생성만 한다"] -->|"tool_calls (실행 요청)"| H["우리 코드<br/>검증 → 실행"]
H --> T1["지식의 구멍<br/>검색·DB 조회<br/>(컷오프 너머, 사설 데이터)"]
H --> T2["정확성의 구멍<br/>계산·코드 실행<br/>(확률이 아닌 결정적 결과)"]
H --> T3["행동의 구멍<br/>파일·예약·결제<br/>(텍스트만으로는 세상이 안 바뀐다)"]
T1 --> M2["observation으로 되먹임"]
T2 --> M2
T3 --> M2
M2 --> M4. Pydantic: 스키마와 검증이 한 몸
03_pydantic_schema.py · 스키마 생성 부분은 키 없이 돈다
- 코드
class BudgetArgs(BaseModel):
"""여행 예산 계산 인자 — 이 docstring이 그대로 설명이 된다."""
nights: int = Field(ge=0, description="숙박 일수")
people: int = Field(ge=1, description="인원 수")
include_flight: bool = Field(default=True, description="항공권 포함 여부")
schema = BudgetArgs.model_json_schema() # ① 모델에게 보여줄 스키마
BudgetArgs.model_validate(raw_args) # ② 도착한 인자의 검증- 실행
docker compose exec lab python examples/03_tools/03_pydantic_schema.py 파이썬 클래스에서 나온 JSON 스키마
=== pydantic 모델에서 뽑은 JSON 스키마 ===
{
"properties": {
"nights": { "minimum": 0, "type": "integer", … },
"people": { "minimum": 1, "type": "integer", … },
"include_flight": { "default": true, "type": "boolean", … }
},
"required": ["nights", "people"], …
}
=== 도착한 인자의 검증도 같은 모델로 ===
정상 인자 → nights=3 people=2 include_flight=True
불량 인자 → ValidationError (ge 제약이 잡았다)명세와 검증이 한 몸이라 어긋날 수가 없습니다.
5. 병렬 도구 호출: 독립 조회는 한 턴에
04_parallel_tools.py · 항공과 숙소, 서로 의존이 없는 조회 2건
- 실행
docker compose exec lab python examples/03_tools/04_parallel_tools.py- 결과
=== 한 턴에 실려 온 도구 요청: 2건 ===
search_flights({"city": "오사카"})
search_hotels({"city": "오사카"})
=== 두 결과를 함께 반영한 답 ===
* 항공권 (최저가 기준): 약 310,000원 (LCC 기준)
* 숙소 (1박 기준): 난바 지역 기준 약 120,000원tool_calls는 배열입니다.
서로 의존이 없으면 모델이 두 요청을 한 턴에 실어 보내고,
왕복이 줄어든 만큼 싸고 빠릅니다.
6. 인자 제약: 스키마는 프롬프트보다 강하다
05_arg_constraints.py · 키 없이 돈다
- 실행
docker compose exec lab python examples/03_tools/05_arg_constraints.py- 결과
"category": {
"anyOf": [ { "enum": ["관광", "식당", "카페"], "type": "string" },
{ "type": "null" } ],
"default": null, …
},
"max_results": { "default": 5, "maximum": 20, "minimum": 1, … },
"required": ["city"]enum: 이 셋 중 하나만default: 안 주면 이 값required밖: 안 줘도 됨
“카테고리는 관광·식당·카페 중 하나로 해줘”라는 문장보다, 스키마에 박힌 enum이 강합니다.
7. tool_choice: 쓸지 말지를 코드가 정한다
06_tool_choice.py · 도구가 전혀 필요 없는 인사말에 세 값을 시험
- 실행
docker compose exec lab python examples/03_tools/06_tool_choice.py- 결과
=== tool_choice = auto (기본) === 인사말에 대한 반응: 그냥 답변
=== tool_choice = none (금지) === 인사말에 대한 반응: 그냥 답변
=== tool_choice = required (강제) === 인사말에 대한 반응: 도구 요청 calc_budgetrequired가 인사에도 예산 도구를 부르게 만들었습니다.
강제는 강력하지만 질문과 무관한 호출도 만듭니다.
제어권을 코드가 가져야 하는 자리에 골라 씁니다.
8. 에러 되먹임: 실패를 알려주면 복구한다
07_tool_error.py · 도구는 THB(태국 바트)를 모른다
- 코드
except ValueError as e:
result = json.dumps({"error": str(e)}, ensure_ascii=False)
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})- 실행
docker compose exec lab python examples/03_tools/07_tool_error.py- 결과
=== [1] get_exchange_rate({'currency': 'THB'}) → 실패를 되먹임 ===
{"error": "지원하지 않는 통화: THB. 지원 목록: ['JPY', 'USD']"}
=== [1] get_exchange_rate({'currency': 'JPY'}) → 성공 === 9. 인자 환각: 스키마는 통과해도 값은 허구일 수 있다
08_hallucinated_args.py · 호텔 목록을 안 알려주고 예약을 시킨다
- 실행
docker compose exec lab python examples/03_tools/08_hallucinated_args.py- 결과
=== 모델이 보낸 인자 ===
{'nights': 3, 'hotel': '오사카 오션뷰 호텔'}
=== 실행 전 검증 ===
차단: Value error, 존재하지 않는 호텔: '오사카 오션뷰 호텔'.
목록: ['난바 그랜드', '우메다 스카이', '신사이바시 인']
→ 스키마는 통과했지만 값이 허구다. 검증이 없었다면 유령 예약이 실행됐다 10. 구조화 출력: LLM을 타입 있는 함수처럼
09_structured_output.py · 실행할 생각이 없어도 스키마로 강제할 수 있다
- 코드
tool = {"type": "function", "function": {
"name": "emit_trip_plan",
"parameters": TripPlan.model_json_schema()}}
resp = completion(…, tools=[tool],
tool_choice={"type": "function",
"function": {"name": "emit_trip_plan"}})
plan = TripPlan.model_validate(json.loads(raw)) # 여기서부터는 파이썬 객체- 실행
docker compose exec lab python examples/03_tools/09_structured_output.py 11. 도구 선택: 이름과 설명이 품질을 가른다
10_tool_selection.py · 같은 10개 도구를 두 벌로 등록
docker compose exec lab python examples/03_tools/10_tool_selection.py- ① 성의 있는 이름·설명
- ② 익명 이름(
tool_0…)과 무성의한 설명
같은 질문을 던집니다: “이번 주말 오사카에 축제 하나요?”
=== 성의 있는 이름·설명 ===
선택된 도구: event_calendar (정답: event_calendar)
=== 익명 이름·무성의한 설명 ===
선택된 도구: tool_0 (정답: tool_8) 구조도: 판단과 실행의 순환
flowchart TD
A["요청: messages (대화 전체)<br/>+ tools (이름·설명·파라미터 스키마)"] --> B{"모델 판단"}
B -->|"도구가 필요하다"| C["tool_calls 요청<br/>어느 도구를, 어떤 인자로"]
C --> D["사용자 컴퓨터에서 실행<br/>인자 검증 → 함수 호출"]
D --> E["결과를 role: tool 메시지로<br/>배열에 추가"]
E --> A2["다시 요청<br/>커진 배열 + 같은 도구 목록"]
A2 --> B
B -->|"이제 충분하다"| F["최종 답 텍스트"]모델은 매번 “다른 도구가 더 필요한가, 이제 답할 수 있는가”만 판단합니다.
이 순환에 종료 조건을 달아 돌리는 것이 6주차의 ReAct입니다.
역할별 흐름: 누가 무엇을 하는가
sequenceDiagram
participant U as 사용자
participant H as 우리 코드<br/>(사용자 컴퓨터)
participant M as LLM API
participant T as 도구<br/>(로컬 함수)
U->>H: "100엔이 얼마야?"
H->>M: messages + 도구 목록(스키마)
M-->>H: tool_calls: get_exchange_rate({"currency": "JPY"})
H->>H: 인자 검증 (스키마·값)
H->>T: get_exchange_rate("JPY") 실행
T-->>H: {"currency": "JPY", "krw": 9.1}
H->>M: 결과를 role: tool로 추가해 재요청
M-->>H: 최종 답 "약 910원입니다"
Note over M,H: 더 필요하면 tool_calls를 반복
H-->>U: 답 표시코드 포인트: agent/tools.py
class BudgetArgs(BaseModel):
"""숙박·식비·항공을 합쳐 여행 예산(원)을 계산한다."""
nights: int = Field(ge=0, le=30, description="숙박 일수")
people: int = Field(ge=1, le=10, description="인원 수")
style: Literal["절약", "보통", "고급"] = Field(default="보통", …)
include_flight: bool = Field(default=True, …)
REGISTRY = {
"search_places": (SearchPlacesArgs, search_places),
"estimate_travel_time": (TravelTimeArgs, estimate_travel_time),
"calc_budget": (BudgetArgs, calc_budget),
}
def run_tool(name: str, raw_arguments: str) -> str:
"""도구 실행의 단일 관문: 검증 → 실행 → JSON 문자열."""