도구 사용(함수 호출)의 파라미터 유형
도구 사용(함수 호출)의 파라미터 유형
Cohere Chat API에서 도구 파라미터와 함께 구조화된 출력을 사용하는 방법에 대한 가이드예요. 지원되는 파라미터 유형과 사용 예시를 다룹니다 (API v2).
출처: 문서
본문
Structured Outputs (Tools)
Structured Outputs 기능은 LLM 응답이 사용자가 지정한 스키마를 엄격히 따를 것임을 보장해요.
이 기능은 두 가지 시나리오(JSON 및 tools)에서 지원되지만, 이 페이지에서는 도구(tools) 시나리오에 초점을 맞춥니다.
사용법(Usage)
tools와 함께 Chat API를 사용할 때 strict_tools 파라미터를 True로 설정하면, 생성된 모든 도구 호출이 지정된 도구 스키마를 따를 것임을 보장해요.
구체적으로 이는 다음을 의미합니다:
- 환각된 도구 이름 없음
- 환각된 도구 파라미터 없음
- 모든
required파라미터가 도구 호출에 포함됨 - 모든 파라미터가 요청된 데이터 유형을 생성함
strict_tools를 활성화하면 API는 도구 이름과 도구 파라미터가 도구 정의에 따라 생성되도록 보장해요. 이는 도구 이름과 파라미터 환각을 없애고, 각 파라미터가 지정된 데이터 유형과 일치하며, 모든 required 파라미터가 모델 응답에 포함되도록 합니다.
또한 이는 더 빠른 개발로 이어져요. 환각을 피하기 위해 모델을 프롬프트 엔지니어링하는 데 많은 시간을 쓸 필요가 없습니다.
strict_tools 파라미터를 True로 설정하면 API 호출로 전달되는 모든 도구에 걸쳐 최대 200개의 필드를 정의할 수 있어요.
PYTHON
response = co.chat(model="command-a-plus-05-2026",
messages=[{"role": "user", "content": "What's the weather in Toronto?"}],
tools=tools,
strict_tools=True
)
중요 참고 사항(Important notes)
strict_tools를 사용할 때 다음 참고 사항이 적용됩니다:
- 이 파라미터는 strict_tools 파라미터를 통해 Chat API V2에서만 지원됩니다 (API V1에서는 지원되지 않아요).
- 최소한 하나의
required파라미터를 지정해야 합니다. 선택 파라미터만 있는 도구는 이 모드에서 지원되지 않아요. - 단일 Chat API 호출에서 모든 도구에 걸쳐 최대 200개의 필드를 정의할 수 있습니다.
지원되는 파라미터 유형(Supported parameter types)
Structured Outputs는 JSON Schema 사양의 하위 집합을 지원해요. 지원 및 미지원 파라미터 목록은 Structured Outputs 문서를 참조하세요.
사용 예시(Usage examples)
이 섹션은 Structured Outputs (Tools)에서 지원되는 JSON Schema 파라미터의 사용 예시를 제공해요.
도우미 코드(Helper code)
이 페이지의 예시들은 각각 도구 스키마와 message(사용자 메시지)를 제공해요. 출력을 얻으려면 아래 도우미 코드처럼 해당 값을 Chat 엔드포인트 호출에 전달하면 됩니다.
Cohere 플랫폼
PYTHON
# ! pip install -U cohere
import cohere
co = cohere.ClientV2(
"COHERE_API_KEY"
) # Get your free API key here: https://dashboard.cohere.com/api-keys
프라이빗 배포(Private deployment)
PYTHON
# ! pip install -U cohere
import cohere
co = cohere.ClientV2(
api_key="", # Leave this blank
base_url="<YOUR_DEPLOYMENT_URL>",
)
PYTHON
response = co.chat(
# The model name. Example: command-a-plus-05-2026
model="MODEL_NAME",
# The user message. Optional - you can first add a `system_message` role
messages=[
{
"role": "user",
"content": message,
}
],
# The tool schema that you define
tools=tools,
# This guarantees that the output will adhere to the schema
strict_tools=True,
# Typically, you'll need a low temperature for more deterministic outputs
temperature=0,
)
for tc in response.message.tool_calls:
print(f"{tc.function.name} | Parameters: {tc.function.arguments}")
cURL
curl --request POST \
--url https://api.cohere.ai/v2/chat \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header "Authorization: bearer ***" \
--data '{
"model": "command-a-plus-05-2026",
"messages": [
{
"role": "user",
"content": "What'\''s the weather in Toronto?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco."
}
},
"required": ["location"]
}
}
}
],
"strict_tools": true,
"temperature": 0
}'
기본 유형(Basic types)
String
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location to get the weather, example: San Francisco.",
}
},
"required": ["location"],
},
},
},
]
message = "What's the weather in Toronto?"
예제 응답:
get_weather
{
"location": "Toronto"
}
Integer
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "add_numbers",
"description": "Adds two numbers",
"parameters": {
"type": "object",
"properties": {
"first_number": {
"type": "integer",
"description": "The first number to add.",
},
"second_number": {
"type": "integer",
"description": "The second number to add.",
},
},
"required": ["first_number", "second_number"],
},
},
}
]
message = "What is five plus two"
예제 응답:
add_numbers
{
"first_number": 5,
"second_number": 2
}
Float
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "add_numbers",
"description": "Adds two numbers",
"parameters": {
"type": "object",
"properties": {
"first_number": {
"type": "number",
"description": "The first number to add.",
},
"second_number": {
"type": "number",
"description": "The second number to add.",
},
},
"required": ["first_number", "second_number"],
},
},
}
]
message = "What is 5.3 plus 2"
예제 응답:
add_numbers
{
"first_number": 5.3,
"second_number": 2
}
Boolean
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "reserve_tickets",
"description": "Reserves a train ticket",
"parameters": {
"type": "object",
"properties": {
"quantity": {
"type": "integer",
"description": "The quantity of tickets to reserve.",
},
"trip_protection": {
"type": "boolean",
"description": "Indicates whether to add trip protection.",
},
},
"required": ["quantity", "trip_protection"],
},
},
}
]
message = "Book me 2 tickets. I don't need trip protection."
예제 응답:
reserve_tickets
{
"quantity": 2,
"trip_protection": false
}
배열(Array)
특정 유형 포함(With specific types)
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"locations": {
"type": "array",
"items": {"type": "string"},
"description": "The locations to get weather.",
}
},
"required": ["locations"],
},
},
}
]
message = "What's the weather in Toronto and New York?"
예제 응답:
get_weather
{
"locations": [
"Toronto",
"New York"
]
}
특정 유형 없음(Without specific types)
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"locations": {
"type": "array",
"description": "The locations to get weather.",
}
},
"required": ["locations"],
},
},
}
]
message = "What's the weather in Toronto and New York?"
예제 응답:
get_weather
{
"locations": [
"Toronto",
"New York"
]
}
리스트의 리스트(Lists of lists)
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "maxPoints",
"description": "Finds the maximum number of points on a line.",
"parameters": {
"type": "object",
"properties": {
"points": {
"type": "array",
"description": "The list of points. Points are 2 element lists [x, y].",
"items": {
"type": "array",
"items": {"type": "integer"},
"description": "A point represented by a 2 element list [x, y].",
},
}
},
"required": ["points"],
},
},
}
]
message = "Please provide the maximum number of collinear points for this set of coordinates - [[1,1],[2,2],[3,4],[5,5]]."
예제 응답:
maxPoints
{
"points": [
[1,1],
[2,2],
[3,4],
[5,5]
]
}
기타(Others)
중첩 객체(Nested objects)
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "search_furniture_products",
"description": "Searches for furniture products given the user criteria.",
"parameters": {
"type": "object",
"properties": {
"product_type": {
"type": "string",
"description": "The type of the product to search for.",
},
"features": {
"type": "object",
"properties": {
"material": {"type": "string"},
"style": {"type": "string"},
},
"required": ["style"],
},
},
"required": ["product_type"],
},
},
}
]
message = "I'm looking for a dining table made of oak in Scandinavian style."
예제 응답:
search_furniture_products
{
"features": {
"material": "oak",
"style": "Scandinavian"
},
"product_type": "dining table"
}
열거형(Enums)
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "fetch_contacts",
"description": "Fetch a contact by type",
"parameters": {
"type": "object",
"properties": {
"contact_type": {
"type": "string",
"description": "The type of contact to fetch.",
"enum": ["customer", "supplier"],
}
},
"required": ["contact_type"],
},
},
}
]
message = "Give me vendor contacts."
예제 응답:
fetch_contacts
{
"contact_type": "supplier"
}
Const
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gets the weather of a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The location to get weather.",
},
"country": {
"type": "string",
"description": "The country for the weather lookup",
"const": "Canada",
},
},
"required": ["location", "country"],
},
},
}
]
message = "What's the weather in Toronto and Vancouver?"
예제 응답:
get_weather
{
"country": "Canada",
"location": "Toronto"
}
---
get_weather
{
"country": "Canada",
"location": "Vancouver"
}
---
Pattern
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "query_product_by_sku",
"description": "Queries products by SKU pattern",
"parameters": {
"type": "object",
"properties": {
"sku_pattern": {
"type": "string",
"description": "Pattern to match SKUs",
"pattern": "[A-Z]{3}[0-9]{4}",
}
},
"required": ["sku_pattern"],
},
},
}
]
message = "Check the stock level of this product - 7374 hgY"
예제 응답:
query_product_by_sku
{
"sku_pattern": "HGY7374"
}
Format
PYTHON
tools = [
{
"type": "function",
"function": {
"name": "book_hotel",
"description": "Books a hotel room for a specific check-in date",
"parameters": {
"type": "object",
"properties": {
"hotel_name": {
"type": "string",
"description": "Name of the hotel",
},
"check_in_date": {
"type": "string",
"description": "Check-in date for the hotel",
"format": "date",
},
},
"required": ["hotel_name", "check_in_date"],
},
},
}
]
message = "Book a room at the Grand Hotel with check-in on Dec 2 2024"
예제 응답:
book_hotel
{
"check_in_date": "2024-12-02",
"hotel_name": "Grand Hotel"
}