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

# 구조화된 출력 및 도구 호출

> 모든 모델이 동일한 계약을 지원한다고 가정하지 않고 JSON 모드, 함수 도구 및 기본 도구 경로를 사용하세요.

구조화된 출력 및 도구 호출은 경로별 계약입니다. TokenLab은 여러 공용 API 형식을 전달하므로, 가장 안전한 프로덕션 패턴은 각 제공자 고유의 도구 형상을 해당 경로에 유지하고, 귀하의 애플리케이션에서 모델 출력을 검증하는 것입니다.

## 경로 선택

| 필요                    | 경로                                      | 이 형상 사용                                            |
| --------------------- | --------------------------------------- | -------------------------------------------------- |
| 휴대 가능한 JSON 객체 응답     | `/v1/chat/completions`                  | `response_format: {"type": "json_object"}`         |
| OpenAI 호환 함수 호출       | `/v1/chat/completions`                  | `tools: [{ "type": "function", "function": ... }]` |
| OpenAI 응답 도구          | `/v1/responses`                         | 응답 `tools`, `tool_choice`, 및 `text` 필드             |
| Claude 고유 도구 사용 또는 사고 | `/v1/messages`                          | Anthropic Messages 도구 스키마                          |
| Gemini 함수 선언 또는 내장 도구 | `/v1beta/models/:model:generateContent` | Gemini 고유 `tools` 및 콘텐츠 부분                         |

제공자 고유의 내장 도구를 다른 경로를 통해 전송하고 TokenLab이 이를 조용히 변환할 것이라고 기대하지 마십시오.

## JSON 모드

휴대 가능한 구조화된 응답을 위해 Chat Completions JSON 모드로 시작하세요:

```json theme={null}
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "도시와 날씨를 포함한 JSON 객체를 반환하세요."
    }
  ],
  "response_format": { "type": "json_object" }
}
```

Chat Completions에 대한 안정적인 공유 검증은 `text` 및 `json_object`를 수용합니다. `json_schema`, `strict`, 및 제공자 특정 스키마 강제 적용은 일부 업스트림 경로 또는 변환 경로에 존재할 수 있지만, 이는 모든 TokenLab 경로 및 모델에 걸쳐 보편적인 약속이 아닙니다. 의존하기 전에 선택한 모델에 대해 이를 검증하십시오.

항상 서버에서 반환된 JSON을 파싱하고 검증하십시오. JSON 모드는 형상을 개선하지만, 애플리케이션 수준의 스키마 검증을 대체하지는 않습니다.

## 도구 호출 루프

TokenLab은 귀하의 함수를 실행하지 않습니다. 귀하의 애플리케이션이 루프를 소유합니다:

1. 메시지와 도구 정의를 전송합니다.
2. `tool_calls`, `function_call`, Anthropic `tool_use`, 또는 Gemini 함수 호출 부분에 대한 모델 응답을 읽습니다.
3. 귀하의 백엔드에서 도구를 실행합니다.
4. 동일한 경로에서 요구되는 형식으로 도구 결과를 추가합니다.
5. 모델이 최종 답변을 반환할 때까지 대화를 계속합니다.

도구 루프 전반에 걸쳐 동일한 경로를 유지하십시오. Chat Completions, Responses, Messages, 및 Gemini 형식을 하나의 대화에서 혼합하면 일반적으로 미세한 상태 및 스키마 버그가 발생합니다.

## Chat Completions 예제

```bash theme={null}
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "이름과 이메일을 JSON으로 추출하세요. 필요하다면 고객을 조회하세요."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "이메일로 고객 조회",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'
```

## 스키마 설계

* 스키마를 작고 명시적으로 유지하십시오. 큰 중첩 스키마는 토큰을 추가하고 신뢰성을 감소시킵니다.
* 제품이 계속 진행할 수 없는 값에 대해 필수 필드를 선호하십시오.
* UI 또는 백엔드가 의존하는 닫힌 집합에 대해 enums를 사용하십시오.
* 모델이 형상에 어려움을 겪을 때 프롬프트에 예제를 포함하십시오.
* 지원되지 않는 필드 오류를 계약 피드백으로 취급하십시오. 필드를 제거하거나 이를 문서화한 기본 경로를 사용하십시오.

## 프로덕션 체크리스트

* 경로, 모델, 도구 이름 및 정제된 스키마 형상을 로그에 기록하십시오.
* 부작용을 실행하기 전에 도구 인수를 검증하십시오.
* 도구 실행 전에 귀하의 권한 검사를 적용하십시오.
* 클라이언트 재시도가 동일한 도구 호출을 반복할 수 있을 때 도구 실행을 멱등성 있게 만드십시오.
* 도구가 반환한 비밀을 모델이 볼 수 있는 메시지에 기록하지 마십시오.

## API 참조

| 주제            | 참조                                                         |
| ------------- | ---------------------------------------------------------- |
| 다중 형식 API     | [다중 형식 API](/ko/guides/api-formats)                        |
| 채팅 완료 생성      | [채팅 완료 생성](/ko/api-reference/chat/create-completion)       |
| 응답 생성         | [응답 생성](/ko/api-reference/responses/create-response)       |
| 메시지 생성        | [메시지 생성](/ko/api-reference/messages/create-message)        |
| Gemini 콘텐츠 생성 | [Gemini 콘텐츠 생성](/ko/api-reference/gemini/generate-content) |