> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# 도구 호출

> Agent가 도구에게 시킨 모든 것과 돌아온 것

실행의 진실은 도구 호출에 담겨 있을 때가 많습니다. Agent 답변이 틀렸다면, 도구가 엉뚱한 걸 돌려줬거나, Agent가 엉뚱한 도구를 골랐거나, 맞는 도구를 잘못된 인자로 부른 것입니다. 트레이스가 이 셋을 다 보여줍니다.

## 도구 호출 뷰

실행의 도구 호출마다 이렇게 보여줍니다.

* **도구 이름**과 버전.
* **인자** 모델이 고른 정확한 JSON.
* **응답** 도구의 원본 응답.
* **소요** 부른 뒤 응답까지 걸린 벽시계.
* **재시도** 도구가 다시 시도했다면 그 횟수.
* **비용** 직접 드는 달러 비용(API 가격이 있는 도구).

인자는 문법 강조와 함께, 도구 스키마에 견준 주석을 답니다. 필수인데 빠진 인자는 빨강, 못 알아보는 인자는 노랑입니다.

## "Agent는 왜 이걸 불렀지?"

도구 호출마다 위에 **rationale**이 보입니다. 그 호출을 하게 만든 모델 추론의 조각이죠. 늘 있는 건 아니지만(추론을 안 내놓는 모델도 있습니다), 있으면 "왜" 를 가장 빠르게 아는 방법입니다.

## 흔한 실패 방식

### 엉뚱한 도구

Agent가 `send_slack`을 골라야 할 때 `send_email`을 골랐습니다. 도구 설명을 조이면 풀립니다. Agent는 설명만 보고 고르니까요.

### 잘못된 인자

맞는 도구인데 인자가 틀렸습니다. 흔한 원인은 파라미터 설명이 흐릿한 것입니다. 트레이스가 모델이 정확히 뭘 골랐는지 보여주니 대개 금방 드러납니다.

### 도구 에러

도구가 4xx나 5xx를 돌려줍니다. `Response`에서 에러 본문을 봅니다. 이렇게 다룹니다.

* 도구 설정을 고칩니다(잘못된 URL, 만료된 시크릿).
* 일시적 에러에는 재시도를 답니다.
* 도구 설명이 인자 형태를 Agent에게 미리 일러 주게 합니다.

### 도구는 성공했는데 데이터가 틀림

도구 호출은 통과했는데 돌아온 데이터가 헷갈리게 합니다. Agent가 나쁜 데이터로 추론하죠. 도구 구현을 살펴보세요.

## 도구 응답 살피기

큰 응답(수백 필드짜리 JSON)은 접을 수 있습니다. 기본 뷰는 최상위 키만 보여주고, 누르면 펼쳐집니다.

`Copy as curl`이 로컬에서 디버깅할 수 있게 정확한 요청을 다시 만들어 줍니다.

## 도구 호출 순서

도구를 여럿 부른 실행은 쌓인 순서로 보입니다. 흔한 모습은 이렇습니다.

* **Search → Read → Answer** Agent가 검색하고, 최상위 결과를 읽고, 답합니다.
* **Lookup → Verify → Act** Agent가 엔티티를 조회하고, 두 번째 소스로 확인하고, 행동합니다.
* **Retry 루프** Agent가 도구를 부르고, 특정 에러를 받고, 인자를 고쳐 다시 시도합니다.

순서마다 주석이 붙습니다. `SUCCESS`, `RETRY`, `ABANDONED` 입니다. Abandoned는 Agent가 그 경로를 접었다는 뜻입니다.

## Rewrite 중 부른 도구

검증이 rewrite를 일으켰다면([에이전트 답변 검증](/ko/build/causal-graph/verification) 참고), 두 번째 패스가 다른 도구를 부를 수 있습니다. 두 패스 모두 `Rewrite` 마커로 구분되어 타임라인에 나옵니다.

## 도구 호출을 데이터셋에 담기

도구 호출에서 우클릭 → **Add to dataset**를 누릅니다. 도구 호출의 입력과 출력을 라벨 붙은 예시로 복사합니다. 실제 프로덕션 동작에서 테스트 픽스처를 만들 때 좋습니다.