ساخت و اجرای عامل

تعریف عامل

POST /v1/agents یک تعریف ذخیره‌شده می‌سازد. name برای نمایش، instructions برای رفتار، kind برای مسیر اجرا و model برای عامل گفتگویی استفاده می‌شود. تعریف عامل به‌تنهایی مدل اجرا نمی‌کند و هزینهٔ تولید ندارد.

import json, os, urllib.request, urllib.error

payload = {
    "name": "دستیار پشتیبانی",
    "kind": "chat",
    "model": "z-ai/glm-5.3-flash",
    "instructions": "به فارسی پاسخ بده. اگر اطلاعات کافی نیست، یک پرسش روشن بپرس."
}

request = urllib.request.Request(
    "https://api.sarovi.ir/v1/agents",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
        print(result)
except urllib.error.HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from error

اجرای عامل

با POST /v1/agents/{id}/runs و input درخواست بدهید. عامل chat پاسخ مشابه Responses API دارد و stream را هم می‌پذیرد. instructions ذخیره‌شده به درخواست اضافه می‌شود. برای خواندن تعریف‌ها GET /v1/agents را بزنید و برای حذف DELETE /v1/agents/{id}.

عامل ماندگار

kind می‌تواند research، document، code یا data باشد. این عامل‌ها یک کار در موتور Work ساروی می‌سازند و HTTP 202 با status_url و files_url برمی‌گردانند. مدل و ابزار اجرای آن‌ها از تنظیمات موتور Work می‌آید؛ فیلد model تعریف عامل، مدل این کارها را عوض نمی‌کند.

تعریف خوب بنویسید

نقش را با خروجی مورد انتظار شروع کنید. منابع مجاز، قالب نتیجه و شرایط سؤال پرسیدن را مشخص کنید. دستورالعمل‌ها را کوتاه نگه دارید و دادهٔ متغیر هر اجرا را در input بفرستید. کلید، رمز یا دادهٔ حساب را داخل دستورالعمل ذخیره نکنید.

رصد اجرا

شناسهٔ پاسخ و شناسهٔ run دو مفهوم متفاوت‌اند. برای Work از id و status_url پاسخ 202 استفاده کنید؛ برای پشتیبانی از X-Request-ID. تعریف عامل پروژهٔ دیگری با کلید شما قابل اجرا نیست. ایجاد یک تعریف تازه، مجوز اجرای ابزارهای خارج از قرارداد ساروی به آن نمی‌دهد.