이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- Tool Calling에서 모델과 서버의 책임은 어떻게 나뉘는가?
- read-only tool과 write tool은 왜 다르게 설계해야 하는가?
- tool 호출을 실제 실행하기 전에 서버가 확인해야 할 것은 무엇인가?
개요
Tool Calling은 모델이 외부 도구를 사용할 수 있게 하는 방식이다. 모델은 tool schema를 보고 어떤 tool을 어떤 인자로 호출할지 제안한다. 그러나 실제 실행은 서버가 통제해야 한다.
모델은 의도를 생성하고, 서버는 정책을 집행한다.
핵심 원리
Tool calling 흐름:
- 서버가 모델에게 tool schema를 제공한다.
- 모델이 tool call과 arguments를 생성한다.
- 서버가 arguments를 검증한다.
- 서버가 권한과 정책을 확인한다.
- 서버가 tool을 실행한다.
- tool 결과를 모델 context에 넣거나 사용자에게 반환한다.
이 중 3, 4, 5는 백엔드 책임이다.
Read-only와 Write 분리
read-only tool:
- 문서 검색
- 티켓 조회
- 배포 상태 조회
- 상품 정보 조회
write tool:
- 티켓 생성
- 메일 발송
- 주문 취소
- 권한 변경
- 배포 실행
write tool은 idempotency key, audit log, approval, rate limit이 필요하다.
코드로 이해하기
tool execution gateway를 둔다.
def execute_tool_call(*, actor, tool_call, registry, audit):
tool = registry.get(tool_call.name)
if tool is None:
raise ValueError("unknown_tool")
args = tool.schema.model_validate(tool_call.arguments)
authorization.require_scope(
actor=actor,
scope=tool.required_scope,
)
if tool.mode == "write" and not args.idempotency_key:
raise ValueError("idempotency_key_required")
result = tool.handler(args)
audit.record(
actor_id=actor.id,
tool_name=tool.name,
status="success",
resource_id=result.resource_id,
)
return result모델이 tool call을 만들었다고 바로 실행하지 않는다. gateway에서 검증한다.
백엔드 설계 판단
- 이 tool은 사용자 대신 실행해도 되는가?
- 실행 전 approval이 필요한가?
- 실패 후 retry할 수 있는가?
- 같은 요청이 두 번 오면 어떻게 되는가?
- 결과를 모델에게 다시 넣어도 안전한가?
- tool 결과에 민감정보가 있는가?
장애 상황과 대응
tool 장애:
- 잘못된 tool 선택
- invalid arguments
- 권한 없는 호출
- 중복 실행
- tool timeout
- tool result prompt injection
대응:
- tool별 schema validation
- idempotency
- audit log
- max tool calls
- structured error
- read/write 분리
인프라 협업 포인트
Tool calling은 내부 API 호출량을 증가시킬 수 있다. 인프라팀과 tool별 QPS, timeout, retry, outbound, audit log 저장량을 합의한다.
실전 팁
- tool 이름과 description은 짧고 명확하게 쓴다.
- write tool은 draft 생성부터 시작한다.
- 모델이 만든 tool arguments는 모두 검증한다.
- tool result를 모델에게 줄 때는 데이터로 감싼다.
위험 신호!
- 모델이 만든 tool call을 검증 없이 실행한다.
- write tool에 audit log가 없다.
- side effect tool에 공통 retry가 적용된다.
- tool 권한을 prompt에만 적는다.
확인 질문
확인 질문
- Tool Calling에서 모델의 책임과 서버의 책임은 무엇인가?
- 모델은 호출 의도와 인자를 제안하고, 서버는 검증, 권한, 실행, 감사 책임을 진다.
- write tool을 안전하게 실행하기 위한 최소 장치는 무엇인가?
- idempotency key, 권한 검사, audit log, retry 제한이다.
Spring AI 적용 연결
- Spring AI의 tool API는 서버 메서드를 모델에 노출하는 경계이므로 read-only, approval, idempotency를 먼저 나눠야 한다. 구체 설계는 07. Tool Calling과 Side Effect 방어에서 이어진다.
- 외부 도구를 표준 프로토콜로 묶어야 할 때는 08. MCP Client Server 통합을 함께 본다.