도구 호출

모델이 도구 호출을 제안하면 애플리케이션이 안전하게 실행하고 결과를 전달합니다.

Tool Calling은 모델이 대화에 따라 하나 이상의 도구를 선택하고 호출에 필요한 구조화된 매개변수를 생성하도록 합니다. 모델이 애플리케이션을 대신하여 데이터베이스에 접근하거나 내부 서비스를 호출하거나 쓰기 작업을 실행하지는 않습니다. 실제 도구 실행은 항상 애플리케이션이 담당합니다.

주문 조회, 날씨 확인, 지식베이스 검색, 데이터 계산 및 승인된 명확한 업무 작업에 적합합니다.

모델이 생성한 매개변수를 그대로 실행하지 않습니다

도구 이름과 매개변수는 모두 모델 출력입니다. 실행 전에 JSON 파싱, Schema 검증, 권한 확인 및 업무 허용 목록 검사를 완료해야 합니다. 결제, 삭제, 메시지 전송 등 위험도가 높은 작업에는 사용자 확인과 멱등성 제어도 필요합니다.

전체 호출 루프

1. 도구 정의

명확한 이름, 용도 설명 및 JSON Schema로 도구를 호출할 수 있는 상황과 매개변수 구조를 모델에 알려줍니다.

2. 모델 요청

사용자 입력과 도구 정의를 함께 보냅니다. 모델은 바로 답하거나 도구 호출을 0개, 1개 또는 여러 개 반환할 수 있습니다.

3. 검증 및 실행

도구 이름으로 로컬 구현을 찾고 모든 매개변수와 호출자 권한을 확인한 후 시간 제한을 두고 실행합니다. 모델이 임의의 함수, URL, SQL 또는 Shell 명령을 지정하도록 허용해서는 안 됩니다.

4. 도구 결과 전달

프로토콜이 반환한 호출 ID로 실행 결과를 원래 도구 호출과 연결한 후 모델에 다시 요청합니다.

5. 최종 답변 읽기

모델은 도구 결과로 사용자에게 제공할 답변을 생성하거나 새로운 도구 호출을 제안할 수 있습니다. 애플리케이션은 최대 반복 횟수와 종료 조건을 설정해야 합니다.

읽기 전용 도구 정의

다음 도구는 날씨만 조회하며 외부 쓰기 작업을 수행하지 않습니다:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "지정한 도시의 현재 날씨를 조회합니다",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "도시 이름(예: 상하이)"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["city", "unit"],
      "additionalProperties": false
    }
  }
}

도구 설명에는 “무엇을 하는지”와 “언제 사용하는지”를 명시합니다. 매개변수 이름은 안정적으로 유지하고 열거 값은 가능한 한 제한하며, required와 additionalProperties로 불필요한 입력을 제한합니다.

Chat 도구 호출 루프 실행

다음은 도구 선언, 호출 읽기, 로컬 함수 실행, 결과 전달 및 최종 답변 읽기의 전체 기본 흐름입니다:

import json

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.agtcloud.cn/v1",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "지정한 도시의 현재 날씨를 조회합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                    },
                },
                "required": ["city", "unit"],
                "additionalProperties": False,
            },
        },
    }
]


def get_weather(city: str, unit: str) -> dict[str, str | int]:
    if city != "상하이" or unit != "celsius":
        raise ValueError("이 예시는 상하이의 섭씨 기온만 조회할 수 있습니다")
    return {"city": city, "unit": unit, "temperature": 25}


messages = [{"role": "user", "content": "지금 상하이의 기온은 몇 도인가요?"}]
response = client.chat.completions.create(
    model="MODEL_ID",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

assistant_message = response.choices[0].message
messages.append(assistant_message)

for tool_call in assistant_message.tool_calls or []:
    if tool_call.function.name != "get_weather":
        raise ValueError("모델이 등록되지 않은 도구를 요청했습니다")

    arguments = json.loads(tool_call.function.arguments)
    result = get_weather(**arguments)
    messages.append(
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result, ensure_ascii=False),
        }
    )

if assistant_message.tool_calls:
    final_response = client.chat.completions.create(
        model="MODEL_ID",
        messages=messages,
        tools=tools,
    )
    print(final_response.choices[0].message.content)
else:
    print(assistant_message.content)

운영 애플리케이션은 JSON Schema 검증 라이브러리로 arguments를 확인하고 도구 구현에 독립적인 권한, 시간 초과, 오류 유형 및 감사 기록을 설정해야 합니다.

프로토콜별 도구 호출 표현

프로토콜	도구 정의	모델 호출	도구 결과 전달
Chat Completions	`tools[].function`	Assistant Message의 `tool_calls`	`role: tool` 및 `tool_call_id`
Responses	`tools`의 Function Tool	`function_call` Output Item	`function_call_output` 및 `call_id`
Anthropic Messages	`tools` 및 `input_schema`	`tool_use` Content Block	`tool_result` Content Block
Gemini	`functionDeclarations`	Part의 `functionCall`	Part의 `functionResponse`

필드 이름과 중첩 구조를 혼용해서는 안 됩니다. 전체 구조는 각각 Chat Completions, Responses, Anthropic Messages 및 Gemini Generate Content 레퍼런스에서 확인합니다.

여러 도구 호출과 Streaming

한 번에 도구 하나만 호출한다고 가정하지 않으며, 호출 ID별로 검증, 실행 및 결과 전달을 수행합니다.
서로 독립적이고 업무상 허용되는 읽기 전용 호출만 병렬 실행에 적합합니다.
스트리밍 매개변수는 여러 증분으로 나뉠 수 있으므로 결합이 완료된 후 JSON으로 해석해야 합니다.
도구 결과를 반환한 후에도 모델이 다음 호출을 제안할 수 있으므로 최대 반복 횟수와 전체 시간 제한이 필요합니다.
같은 쓰기 작업을 재시도할 때는 업무 멱등성 키를 사용하여 중복 청구, 전송 또는 리소스 생성을 방지합니다.

실패 처리

도구 실행이 실패하면 성공 결과를 만들어내서는 안 됩니다. 잘못된 매개변수, 권한 부족, 상위 서비스의 일시적 장애 등 민감 정보를 제거한 오류 유형을 모델에 전달하여 사용자에게 설명하거나 허용된 대안을 선택하도록 할 수 있습니다.

내부 스택, 데이터베이스 구조, 접근 토큰, 사설 네트워크 주소 및 민감 정보를 제거하지 않은 타사 응답은 모델이나 사용자에게 직접 전달해서는 안 됩니다.

운영 전 확인 사항

도구는 등록 목록 또는 허용 목록에서만 선택할 수 있습니다.
매개변수는 실행 전에 Schema와 업무 규칙 검증을 통과합니다.
각 도구에 권한, 시간 제한, 최대 결과 크기 및 오류 처리가 있습니다.
위험도가 높은 쓰기 작업은 사용자 확인을 거치며 멱등성과 감사를 지원합니다.
호출 루프에는 최대 반복 횟수가 있으며 모델이 무한히 이어갈 수 없습니다.
스트리밍 도구 매개변수는 전체 수신이 끝난 후에만 실행합니다.

도구 매개변수를 수신하면서 결합하려면 Streaming을, 최종 답변이 JSON Schema를 따르도록 하려면 Structured Output을 참고합니다.

이 페이지의 내용