birchholt 직접 해보고 남기는 기록

LLM 도구 호출(function calling)은 누가 실행할까 — 하네스 코드로 따라가 본 tool_use 한 바퀴

LLM API에 tools를 넘기면 응답에 tool_use나 functionCall이라는 블록이 돌아오는데, 이걸 받아서 무엇을 해야 하는지가 문서만 봐서는 잘 잡히지 않습니다. 이 글은 LLM API를 호출해 본 적은 있지만 도구 호출을 직접 처리해 본 적은 없는 분을 위해 도구 호출 한 번이 메시지 배열 위에서 어떻게 오가는지를 실제 요청·응답 로그로 보여 줍니다. 「에이전트 하네스를 직접 만들어 본다」 시리즈의 2번째 내용입니다. 첫 번째 내용인 대화 배열 글에서는 대화 기록이 매번 통째로 다시 보내는 메시지 배열일 뿐이라는 것을 요청 로그로 확인했습니다. 결론부터 말하면 app.log가 몇 줄이냐는 질문에 돌아온 첫 응답에는 240이라는 숫자가 없었고 run_command에 wc -l app.log를 넣어 불러 달라는 JSON만 있었습니다. 240은 그 JSON을 받은 하네스(모델 바깥에서 도는 내 코드)가 wc를 돌려 얻었고 그 결과를 배열에 붙여 다시 보내자 모델이 답을 냈습니다.

도구는 ‘메뉴’를 같이 보내는 것에서 시작합니다

v2 하네스가 모델에 알려 주는 도구는 두 개입니다. 이름과 설명, 그리고 인자의 모양을 JSON Schema(JSON 값의 구조를 적는 표준 형식)로 적은 것이 전부입니다.

# 원본: harness-engineering-101 src/harness/v2_tools.py (MIT, © 2026 Isuru Wijesiri) — 내용은 그대로, 형식만 black으로 정리
TOOLS = [  # NEW: the menu
    {
        "name": "read_file",
        "description": "Read a text file and return its contents.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
    {
        "name": "run_command",
        "description": "Run a shell command and return stdout+stderr.",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
            "required": ["command"],
        },
    },
]

이 목록은 매 요청 본문에 messages와 함께 실려 갑니다. 모델 쪽에서 보면 “이런 이름의 함수가 있고, 인자는 이렇게 생겼다"는 안내문일 뿐이고 함수 본체는 모델에게 전달되지 않습니다.

모델이 돌려준 것은 실행 결과가 아니라 요청이었습니다

app.log가 몇 줄인지 물었을 때 첫 번째 호출의 응답입니다(Gemini 원본 응답, 서명 값은 길이만 남김).

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "run_command",
              "args": {
                "command": "wc -l app.log"
              },
              "id": "call_2018648"
            },
            "thoughtSignature": "<signature len=604>"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "finishMessage": "Model generated function call(s)."
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 126,
    "candidatesTokenCount": 21,
    "thoughtsTokenCount": 108,
    "totalTokenCount": 255
  }
}

응답 어디에도 240이라는 숫자가 없습니다. 모델이 한 일은 run_command라는 이름과 {"command": "wc -l app.log"}라는 인자를 골라 낸 것까지입니다. 이 JSON을 받아 실제로 wc를 돌리는 것은 하네스의 디스패치 함수(요청에 적힌 이름을 보고 해당 함수로 넘겨 주는 함수)입니다.

# 원본: harness-engineering-101 src/harness/v2_tools.py (MIT, © 2026 Isuru Wijesiri) — 내용은 그대로, 형식만 black으로 정리
def execute_tool(name, args):  # NEW: the dispatch
    """Map the model's JSON request to a real function call."""
    try:
        if name == "read_file":
            return open(args["path"]).read()
        if name == "run_command":
            out = subprocess.run(
                args["command"], shell=True, capture_output=True, text=True, timeout=60
            )
            return out.stdout + out.stderr
        return f"ERROR: unknown tool {name}"
    except Exception as e:
        return f"ERROR: {e}"  # errors go BACK to the model

제가 돌린 Gemini 이식본에서는 이 함수의 본체만 아래에서 설명할 샌드박스 실행기로 바꿨습니다. 마지막 두 return이 내는 ERROR: ... 문자열이 실제로 모델에게 돌아간 장면은 에이전트 루프 글의 로그에 있습니다.

요청과 결과는 배열에 두 줄로 끼어듭니다

도구를 실행한 뒤 하네스는 모델을 한 번 더 부릅니다. 두 번째 호출 직전의 메시지 배열(변환 전, Anthropic 형식)이 이렇습니다.

[
  {
    "role": "user",
    "content": "How many lines are in app.log?"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "call_2018648",
        "name": "run_command",
        "input": {
          "command": "wc -l app.log"
        },
        "_thought_signature": "<signature len=604>"
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "call_2018648",
        "content": "     240 app.log\n"
      }
    ]
  }
]

질문과 답 사이에 두 줄이 끼었습니다. 하나는 모델이 낸 요청(tool_use)을 assistant 차례로 그대로 적은 것이고 다른 하나는 실행 결과(tool_result)를 user 차례로 적은 것입니다. 로그(runs/v2-1.json calls[1])에서 실행 결과가 든 원소의 역할은 user입니다. 두 줄을 이어 주는 것은 id와 tool_use_id의 일치입니다.

해당 부분의 원본 코드도 짧습니다.

# 원본: harness-engineering-101 src/harness/v2_tools.py (MIT, © 2026 Isuru Wijesiri) — 내용은 그대로, 형식만 black으로 정리
elif block["type"] == "tool_use":  # NEW: honor ONE request
    print(f"\n[tool] {block['name']}({json.dumps(block['input'])})")
    result = execute_tool(block["name"], block["input"])
    messages.append(
        {
            "role": "user",
            "content": [
                {"type": "tool_result", "tool_use_id": block["id"], "content": result}
            ],
        }
    )
    reply2 = call_llm(messages)  # let the model react once

두 번째 호출의 응답은 “There are 240 lines in app.log.“라는 텍스트였고(실제 응답에는 240에 마크다운 굵게, app.log에 코드 표시가 붙어 있었습니다) 실제 파일도 240줄입니다. 두 호출의 토큰은 각각 255·341, 합계 596이었고 응답 시간은 1.975초와 1.641초였습니다(runs/v2-1.json). 두 번째 호출의 입력 토큰이 126에서 276으로 늘어난 것은 위의 두 줄이 배열에 붙어서 다시 전송됐기 때문입니다.

read_file로 config/service.yaml을 읽어 타임아웃을 세 줄로 요약해 달라고 한 실행(runs/v2-2.json)도 같은 모양으로 지나갔습니다. 요약에 나온 값(읽기 타임아웃 5000ms, 재시도 3회와 100/400/1600ms 백오프(재시도 사이에 기다리는 시간), DB 3000ms)은 가상 설정 파일의 값과 같았습니다.

같은 대화를 Gemini 형식으로 바꾸면

위 배열이 어댑터를 거쳐 Gemini로 나간 실제 요청의 contents입니다.

[
  {
    "role": "user",
    "parts": [
      {
        "text": "How many lines are in app.log?"
      }
    ]
  },
  {
    "role": "model",
    "parts": [
      {
        "functionCall": {
          "id": "call_2018648",
          "name": "run_command",
          "args": {
            "command": "wc -l app.log"
          }
        },
        "thoughtSignature": "<signature len=604>"
      }
    ]
  },
  {
    "role": "user",
    "parts": [
      {
        "functionResponse": {
          "id": "call_2018648",
          "name": "run_command",
          "response": {
            "result": "     240 app.log\n"
          }
        }
      }
    ]
  }
]

뼈대는 같고 이름이 다릅니다. 이번 실습에서 변환해야 했던 차이를 표로 옮기면 이렇습니다.

항목Anthropic (원본 코드)Gemini (이번 실습)
역할 이름user / assistantuser / model
메시지 본문content (문자열 또는 블록 배열)parts 배열
시스템 프롬프트최상위 system별도 systemInstruction
도구 목록tools[{name, description, input_schema}]tools[{functionDeclarations[{name, description, parameters}]}]
도구 요청tool_use{id, name, input}functionCall{id, name, args}
도구 결과tool_result{tool_use_id, content}functionResponse{id, name, response: 객체}
도구 요청 신호stop_reason: "tool_use"finishReason: "STOP" (도구 요청이 있어도)
추가로 돌려줘야 하는 값추론(thinking)을 켜면 signature가 든 thinking 블록을 그대로 (원본 코드는 응답 content를 통째로 다시 넣어 따로 다루지 않음)응답 파트에 붙어 오는 thoughtSignature

JSON Schema는 이름만 input_schema에서 parameters로 바꿔 그대로 넘겼고 Gemini가 받아들였습니다.

손이 간 곳은 세 군데였습니다. 첫째, functionResponse는 id만으로 부족하고 함수 이름과 객체 형태의 response를 요구해서 어댑터가 앞선 tool_use의 id→이름 표를 만들어 채우고 결과 문자열을 {"result": ...}로 감쌌습니다. 둘째, 위 응답에서 보듯 Gemini는 함수 호출을 냈는데도 finishReason이 STOP이었습니다. 그래서 “도구를 불렀는가"는 응답에 functionCall 파트가 있는지로 판단해야 했습니다. 셋째, 이번 실행에서 Gemini는 응답 파트에 불투명한 thoughtSignature를 붙여 보냈습니다. 로그 전체에서 관찰된 길이는 164자에서 4,996자 사이였습니다. 원본 코드는 응답을 통째로 배열에 다시 넣으니 이런 값을 따로 다룰 일이 없지만 형식을 변환하는 어댑터는 이것을 블록의 _thought_signature 필드에 보관했다가 다음 요청에 그대로 돌려줘야 했습니다.

# 원본: harness-engineering-101 (MIT, © 2026 Isuru Wijesiri) — Gemini용으로 수정·추가한 gemini/adapter.py 일부
        fr = cand.get("finishReason")
        if n_call:
            stop = "tool_use"
        elif fr == "MAX_TOKENS":
            stop = "max_tokens"
        else:
            stop = "end_turn"

id도 짚어 둘 만합니다. 이번 실행에서 gemini-3.6-flash는 모든 functionCall에 call_2018648 같은 id를 직접 붙여 보냈고 저는 id가 없을 때를 대비한 생성 코드만 남겨 두었습니다.

요청을 한 번만 받아 주면 생기는 일

v2 하네스는 사용자 한 턴에 도구 요청을 딱 한 번만 처리합니다. 결과를 받은 모델이 도구를 또 요청하면 그 요청은 버려지고 다음 사용자 입력으로 넘어갑니다. 원본 코드의 주석에도 그렇게 적혀 있는 의도된 한계입니다. 서비스별 ERROR 줄 수를 세 달라고 하자 바로 그 일이 났습니다(runs/v2-3.json).

[
  {
    "kind": "tool",
    "name": "run_command",
    "input": {
      "command": "ls -la"
    },
    "blocked": false
  },
  {
    "kind": "dropped_tool_calls",
    "calls": [
      {
        "name": "run_command",
        "input": {
          "command": "head -n 20 app.log"
        }
      }
    ]
  },
  {
    "kind": "tool",
    "name": "run_command",
    "input": {
      "command": "grep \"ERROR\" app.log | grep -E \"order-api|payment-worker|search-gw\" | head -n 30"
    },
    "blocked": false
  },
  {
    "kind": "dropped_tool_calls",
    "calls": [
      {
        "name": "run_command",
        "input": {
          "command": "grep \" ERROR \" app.log | awk '{print $3}' | sort | uniq -c"
        }
      }
    ]
  }
]

모델은 두 턴 모두 도구 하나를 쓴 뒤 다음 도구를 원했고 하네스가 그걸 버리는 바람에 사용자는 두 턴 연속 텍스트 답을 한 줄도 받지 못했습니다. 네 번의 호출에 3,257토큰을 썼습니다. 이 한계를 푸는 것이 다음 회의 주제인 루프입니다.

이 실행에서 형식 쪽으로도 하나 배웠습니다. 버려진 요청은 배열에 functionCall로 남아 있고 짝이 되는 functionResponse 없이 바로 다음 사용자 텍스트가 이어졌는데, Gemini는 그 요청에도 HTTP 200으로 답했습니다.

모델이 고른 문자열이 셸로 들어갑니다

원본 execute_tool을 다시 보면 run_command는 모델이 만든 문자열을 subprocess.run(..., shell=True)에 그대로 넘깁니다. 모델이 rm을 고르면 rm이 돌고 curl을 고르면 네트워크로 나갑니다. 그 사이에 사람의 확인도, 경로 제한도 없습니다. 그래서 이식본에서는 이 자리에 허용목록 실행기(gemini/sandbox.py)를 넣었습니다.

허용목록을 미리 생각해 둔 것만으로는 부족했습니다. 위 v2-3 실행에서 모델이 고른 ls -la가 그대로 실행됐고 그 출력에 들어 있던 파일 소유자, 즉 제 로컬 OS 사용자 이름과 그룹이 무료 등급 Gemini로 전송됐습니다. 무료 등급은 프롬프트가 학습에 쓰일 수 있는 조건이라 되돌릴 수 없는 유출입니다. 그 뒤로 ls의 긴 목록 옵션(-l·-n·-o·-g)을 막았습니다. 허용목록은 “위험한 명령"만이 아니라 “출력에 무엇이 실려 나가는가"까지 보고 정해야 한다는 것을 이 실행에서 처음 체감했습니다.

허용목록이 막은 것은 루프 버전(v3)을 돌렸을 때 훨씬 많이 드러났습니다. rm이 막힌 모델이 Python, 직접 쓴 스크립트, 다른 인터프리터로 방법을 바꿔 가며 다시 시도한 기록과 그 과정에서 허용목록의 빈틈이 드러난 경위는 에이전트 루프 글에 모았습니다.

확인하지 못한 것

실습 환경

공개된 교재 레포 harness-engineering-101의 하네스 코드(MIT 라이선스)를 받아 호출부와 실행부만 바꿔 돌렸습니다. 원본은 Anthropic Messages API를 호출하는데, 저는 Gemini API 키만 있어서 호출부를 gemini-3.6-flash 모델로 바꾸는 어댑터를 따로 만들었습니다. 하네스 본체의 루프와 메시지 구조는 원본의 Anthropic 형식 그대로 두고 요청을 보내기 직전과 응답을 받은 직후에만 형식을 바꿉니다. 그래서 같은 대화를 변환 전 Anthropic 형식과 변환 후 Gemini 형식을 나란히 로그에 남길 수 있었습니다.

모델이 읽는 파일은 고정 시드(같은 값을 넣으면 매번 같은 내용이 나오게 하는 난수 시작값)로 만든 가상 데이터입니다. app.log는 가상의 서비스 세 개(order-api·payment-worker·search-gw)가 찍은 240줄짜리 로그이고 config/service.yaml은 타임아웃 값이 적힌 가상 설정 파일입니다. 모델이 실행하는 명령은 전용 sandbox/ 디렉터리 안에서만 돕니다. 이 제한을 건 이유는 본문 「모델이 고른 문자열이 셸로 들어갑니다」에서 다뤘습니다.

원 레포: harness-engineering-101. 본문은 CC BY-NC-ND 4.0이고 이 글은 본문을 인용하거나 번역하지 않았습니다. 코드는 MIT, Copyright (c) 2026 Isuru Wijesiri(LICENSE-CODE)입니다. 이 글은 그 코드를 직접 실행한 기록입니다.