ابزارها و فراخوانی ابزار

در Chat Completions، مدل می‌تواند به‌جای حدس‌زدن، از اپلیکیشن شما بخواهد یک ابزار را اجرا کند. این قابلیت با tools، tool_choice و tool_calls شناخته می‌شود.

اصل مهم: مدل ابزار را اجرا نمی‌کند. مدل فقط یک درخواست ساختاریافته برای اجرای ابزار می‌سازد. اجرای واقعی، اعتبارسنجی، دسترسی و ثبت نتیجه باید در سرویس شما انجام شود.

وضعیت پشتیبانی در گدارAI

گدارAI در مسیر POST /v1/chat/completions فیلدهای OpenAI-compatible مربوط به ابزارها را پشتیبانی می‌کند: tools، tool_choice، parallel_tool_calls، پاسخ tool_calls و پیام بعدی با role: "tool" و tool_call_id.

این پشتیبانی به مدل و ارائه‌دهنده وابسته است. در مسیرهای ارائه‌دهنده‌ای که قرارداد OpenAI-compatible را مستقیم می‌پذیرند، گدارAI این فیلدها را بدون حذف به ارائه‌دهنده می‌فرستد و پاسخ ابزار را به همان شکل OpenAI-compatible برمی‌گرداند. اگر ارائه‌دهنده یا مسیر انتخابی از ابزارها پشتیبانی نکند، درخواست با خطای روشن رد می‌شود.

اطلاع

گدارAI ابزار شما را اجرا نمی‌کند. پس از دریافت tool_calls، سرویس شما باید ابزار مجاز را اجرا کند و نتیجه را با role: "tool" و tool_call_id همان فراخوان به پیام‌ها اضافه کند.

چه مسئله‌ای را حل می‌کند؟

مدل به‌صورت پیش‌فرض به داده‌های زنده و داخلی شما دسترسی ندارد؛ مثلاً:

• وضعیت سفارش
• موجودی انبار
• داده حساب کاربر
• جست‌وجوی داخلی اسناد
• سرویس‌های عملیاتی سازمان

با فراخوانی ابزار، مدل می‌تواند بگوید «برای پاسخ دقیق، این تابع را با این ورودی اجرا کن». سپس سرویس شما نتیجه را به مدل برمی‌گرداند تا پاسخ نهایی ساخته شود.

تعریف ابزار

هر ابزار معمولاً یک function با سه بخش دارد:

• name: نام پایدار و قابل فهم برای ماشین.
• description: توضیح کوتاه درباره اینکه ابزار چه زمانی باید استفاده شود.
• parameters: schema ورودی ابزار.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Get the latest status for a customer order by order id.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "Customer order id"
                    }
                },
                "required": ["order_id"],
                "additionalProperties": False
            }
        }
    }
]

نام‌هایی مثل process یا do_action مبهم‌اند. نام ابزار را عملی و دقیق انتخاب کنید؛ مثلاً get_order_status یا search_support_articles.

دریافت tool call

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 را بگو."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Customer order id"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": False
        }
      }
    }
  ],
  "tool_choice": "auto"
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 را بگو."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Customer order id"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 را بگو."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Customer order id"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "user",
          "content": "وضعیت سفارش A-1024 را بگو."
        }
      ],
    tools=[
        {
          "type": "function",
          "function": {
            "name": "get_order_status",
            "description": "Get the latest status for a customer order by order id.",
            "parameters": {
              "type": "object",
              "properties": {
                "order_id": {
                  "type": "string",
                  "description": "Customer order id"
                }
              },
              "required": [
                "order_id"
              ],
              "additionalProperties": False
            }
          }
        }
      ],
    tool_choice="auto"

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 را بگو."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Customer order id"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
});

console.log(response);

در این مرحله هنوز هیچ ابزار واقعی اجرا نشده است. شما فقط تصمیم مدل را دریافت کرده‌اید.

چرخه کامل اجرای ابزار

الگوی کامل معمولاً چهار گام دارد:

1. پیام کاربر را همراه تعریف ابزارها به مدل می‌فرستید.
2. مدل یک یا چند tool_calls برمی‌گرداند.
3. سرویس شما ابزار مجاز را اجرا می‌کند.
4. نتیجه ابزار را با role: "tool" به مدل برمی‌گردانید تا پاسخ نهایی ساخته شود.

import json
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

messages = [
    {"role": "user", "content": "وضعیت سفارش A-1024 را بگو."}
]

first_response = client.chat.completions.create(
    model="openai:default:gpt-4o-mini",
    messages=messages,
    tools=tools,
)

assistant_message = first_response.choices[0].message

if assistant_message.tool_calls:
    messages.append(assistant_message.model_dump(exclude_none=True))

    for tool_call in assistant_message.tool_calls:
        if tool_call.function.name != "get_order_status":
            raise ValueError("Unsupported tool")

        args = json.loads(tool_call.function.arguments)
        order_id = args["order_id"]

        # این بخش باید در سرویس شما با کنترل دسترسی واقعی اجرا شود.
        result = {
            "order_id": order_id,
            "status": "shipped",
            "estimated_delivery": "2026-07-18"
        }

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

    final_response = client.chat.completions.create(
        model="openai:default:gpt-4o-mini",
        messages=messages,
        tools=tools,
    )

    print(final_response.choices[0].message.content)

نگه‌داشتن پیام assistant با model_dump(exclude_none=True) مهم است، چون tool_calls و بعضی داده‌های وابسته به مدل باید در تاریخچه باقی بمانند.

کنترل با tool_choice

مقدار	رفتار
auto	مدل خودش تصمیم می‌گیرد ابزار لازم است یا نه.
none	مدل نباید ابزار صدا بزند.
required	مدل باید یک ابزار انتخاب کند.
object اختصاصی	مدل را به ابزار مشخصی محدود می‌کند.

نمونه اجبار به ابزار خاص:

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 چیست؟"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": False
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_order_status"
    }
  }
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 چیست؟"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_order_status"
    }
  }
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 چیست؟"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_order_status"
    }
  }
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "user",
          "content": "وضعیت سفارش A-1024 چیست؟"
        }
      ],
    tools=[
        {
          "type": "function",
          "function": {
            "name": "get_order_status",
            "description": "Get the latest status for a customer order by order id.",
            "parameters": {
              "type": "object",
              "properties": {
                "order_id": {
                  "type": "string"
                }
              },
              "required": [
                "order_id"
              ],
              "additionalProperties": False
            }
          }
        }
      ],
    tool_choice={
        "type": "function",
        "function": {
          "name": "get_order_status"
        }
      }

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش A-1024 چیست؟"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the latest status for a customer order by order id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_order_status"
    }
  }
});

console.log(response);

required یا اجبار به ابزار خاص برای مسیرهایی مناسب است که پاسخ بدون داده واقعی قابل قبول نیست؛ مثل قیمت، موجودی، وضعیت سفارش یا اطلاعات حساب.

امنیت و اعتبارسنجی

با tool_calls مثل ورودی خارجی رفتار کنید:

• نام ابزار را با فهرست مجاز خود مقایسه کنید.
• arguments را parse و validate کنید.
• دسترسی کاربر یا سرویس را جداگانه بررسی کنید.
• عملیات حساس را بدون تایید لازم انجام ندهید.
• نتیجه ابزار را کوتاه، دقیق و قابل پردازش برگردانید.

مدل نباید اجازه اجرای مستقیم کد یا دسترسی مستقیم به پایگاه داده شما را داشته باشد.

طراحی schema خوب

• برای مقادیر محدود از enum استفاده کنید.
• required را دقیق بنویسید.
• additionalProperties: False را برای ورودی‌های حساس فعال کنید.
• توضیح ابزار را با نیت کاربر بنویسید، نه با جزئیات داخلی سیستم.
• خروجی ابزار را تا حد امکان JSON کوچک و پایدار نگه دارید.

اثر روی حافظه نهان و استدلال

درخواست‌هایی که ابزار دارند معمولاً مثل درخواست‌های متنی ساده قابل استفاده در حافظه نهان نیستند. اگر مدل‌های استدلالی یا Extended Thinking هم فعال باشند، کامل نگه‌داشتن پیام assistant اهمیت بیشتری پیدا می‌کند، چون ممکن است داده‌های لازم برای ادامه زمینه استدلالی در همان پیام باشد.

اشتباه‌های رایج

• اجرای کورکورانه نام ابزار و آرگومان‌های مدل.
• تعریف ابزارهای خیلی کلی و مبهم.
• نداشتن اعتبارسنجی سمت سرویس.
• برنگرداندن نتیجه ابزار با role: "tool".
• حذف پیام assistant حاوی tool_calls از تاریخچه.
• برگرداندن خروجی طولانی و نامنظم از ابزار.

جمع‌بندی

ابزارها راه اتصال مدل به داده و عملیات واقعی محصول شما هستند. برای استفاده قابل اعتماد، schema دقیق بنویسید، اجرای ابزار را در سرویس امن خودتان نگه دارید، نتیجه را به تاریخچه برگردانید و رفتار هر ابزار را در گزارش رخدادها و سنجه‌ها پایش کنید.