مدیریت دستیارها (Agent)

این API برای مدیریت دستیارها در سیستم استفاده می‌شود. شما می‌توانید از این API برای ایجاد، دریافت و حذف دستیارها استفاده کنید. این API قابلیت‌هایی را برای تنظیم مشخصات دستیار، اعمال تنظیمات مختلف و انجام عملیات‌های مختلف مانند حذف دستیار فراهم می‌آورد.

• POST: ایجاد دستیار جدید.
• GET: دریافت لیستی از دستیارها یا جزئیات یک دستیار خاص.
• DELETE: حذف یک دستیار خاص.
• PATCH: به‌روزرسانی اطلاعات یک دستیار موجود.

---

برای تمامی اکشن‌ها، هدرهای زیر باید ارسال شوند:

هدرها (Headers)

هدر	مقدار	توضیح
Authorization	Token api-token	توکن احراز هویت
Content-Type	application/json	نوع محتوا (JSON). برای درخواست‌های POST، PATCH ضروری است.

1. ایجاد دستیار جدید (POST)

این سرویس برای ایجاد یک دستیار جدید استفاده می‌شود. در این درخواست باید اطلاعات دستیار مانند name, llm_provider, tools و description را ارسال کنید.

مسیر سرویس

POST /api/v1/b2b/agents/

---

ساختار بدنه درخواست (Request Body)

ورودی‌ها (inputs)

نام	نوع	اجباری	توضیح
name	رشته	بله	نام دستیار جدید که باید منحصر به فرد باشد.
llm_provider	شناسه UUID	بله	شناسه دستیار زبان مدل (LLM Provider) که برای این دستیار استفاده می‌شود.
description	رشته	خیر	توضیحات prompt که به دستیار داده میشود.
tools	لیست UUID	خیر	لیستی از شناسه‌های ابزارهایی که به این دستیار اختصاص داده شده است.
knowledge_base	لیست عددی	خیر	لیستی از شناسه های پایگاه دانش‌های مرتبط با این دستیار که می‌تواند به عنوان منابع استفاده شود. (اختیاری)
about_project	رشته	خیر	اطلاعات اضافی در مورد پروژه مرتبط با این دستیار. (اختیاری)
tone_of_voice	رشته	خیر	لحن یا استایل مورد استفاده برای دستیار. (اختیاری)
config	شیء JSON	خیر	پارامترهای پیکربندی مدل دستیار. این فیلد می‌تواند شامل تنظیمات خاصی باشد که در مورد نحوه کار مدل توضیح می‌دهد. (اختیاری)
opener	شیء JSON	خیر	شامل سوالات اصلی و گزینه‌های پیشنهادی برای شروع مکالمه با دستیار. (اختیاری)

مثال:

{
    "name": "My Agent",
    "description": "به عنوان پشتیبان سایت عمل کن",
    "llm_provider": "f5691a19-3fb8-43a4-baa4-d9a445e75a10",
    "about_project": "این پروژه در مورد ارائه بهترین خدمات در زمنیه هوش مصنوعی در ایران است.",
    "tone_of_voice": "رسمی",
    "opener": {
        "main_question": "در چه زمنیه ای سوال دارید.",
        "options": [
            "هزینه خدمات",
            "پشتیبانی رایگان ساخت دستیار"
        ]
    },
    "tools": [
        "8212d01f-0692-4ecc-b35f-71e04ecfdcd9",
        "3e2301ba-ea40-44cd-bf16-05a2b8ab5c6d"
    ],
    "knowledge_base": [
        100
    ],
    "config": {
        "temperature": 0.4,
        "top_p": 0.8,
        "presence_penalty": 0.2,
        "frequency_penalty": 0.2
    }
}

---

مثال با CURL

curl --location 'https://app.houshyar24.ir/api/v1/b2b/agents/' \
--header 'Authorization: Token <your-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name":"My Agent",
    "llm_provider":"4c61fefb-7649-4f4b-bc67-76ae06b73fd6",
    "tools":["cfb12e95-77e9-4f9c-8265-de55d09d21ff", "5988772b-66ac-47f8-9b80-2bd6fa08db7d"],
    "description":"An agent for customer service."
}'

---

پاسخ موفق (201)

{
    "id": 1,
    "uuid": "5647803b-6151-4d43-8617-d1e8f9e407a6",
    "type": "agent",
    "name": "My Agent",
    "llm_provider": "4c61fefb-7649-4f4b-bc67-76ae06b73fd6",
    "tools": [
        "5988772b-66ac-47f8-9b80-2bd6fa08db7d",
        "cfb12e95-77e9-4f9c-8265-de55d09d21ff"
    ],
    "knowledge_base": [],
    "description": "An agent for customer service.",
    "about_project": null,
    "tone_of_voice": null,
    "created_at": "2025-12-14T15:16:27.081973+03:30",
    "updated_at": "2025-12-14T15:16:33.393242+03:30",
    "status": "ready",
    "config": {},
    "opener": {
        "main_question": "",
        "options": []
    }
}

2. دریافت لیست دستیارها (GET)

این سرویس برای دریافت لیست تمامی دستیارهای موجود در سیستم استفاده می‌شود. می‌توانید نتایج را با پارامترهای limit و offset صفحه‌بندی کنید.

مسیر سرویس

GET /api/v1/b2b/agents/

---

پارامترهای مسیر (Path Parameters)

نام	نوع	مکان	اجباری	توضیح
limit	عدد صحیح	query	خیر	تعداد نتایج در هر صفحه
offset	عدد صحیح	query	خیر	ایندکس شروع برای نتایج

نمونه فراخوانی (cURL)

curl --location 'https://app.houshyar24.ir/api/v1/b2b/agents' \
--header 'Authorization: Token <your-token>' \
--data ''

---

پاسخ موفق (200)

[
    {
        "id": 1,
        "name": "هوش‌یار",
        "uuid": "2f7822f7-49ed-4509-8dab-cf0215101c50",
        "image": null,
        "favicon": null,
        "type": "agent",
        "llm_name": "gpt-4o-mini",
        "tools": [
            {
                "id": 4,
                "logo": null,
                "display_name": "serper",
                "description": "",
                "is_active": true,
                "uuid": "77db5bcf-370d-4322-94a8-537c3cb41cb9",
            },
            {
                "id": 10,
                "logo": "http://127.0.0.1:8000/media/tool/None/7645664662a9450c9f8e15ed0e7c19b5.png",
                "display_name": "FLUX Schnell",
                "description": "",
                "is_active": true,
                "uuid": "01e9fea0-5992-461d-90ab-6d537d49870f",
                "credit_type": "basic",
                "amount": 0
            },
            {
                "id": 8,
                "logo": "http://127.0.0.1:8000/media/tool/None/82a52dcd7d3c49ff809a803de885a638.png",
                "display_name": "Current Time",
                "description": "",
                "categories": [
                    {
                        "name": "زمان",
                        "description": ""
                    }
                ],
                "is_active": true,
                "uuid": "b30139fe-85bd-4a82-a360-c483b0852e5c",
                "credit_type": "basic",
                "amount": 0
            }
        ],
        "created_at": "2025-03-25T12:41:06.984468+03:30",
        "config": {},
        "opener": null,
        "status": "ready"

    }
]

3. دریافت یک دستیار خاص (GET)

این سرویس برای دریافت اطلاعات یک دستیار خاص با استفاده از شناسه id استفاده می‌شود

مسیر سرویس

GET /api/v1/b2b/agents/{agent_id}/

---

پارامترهای مسیر (Path Parameters)

نام	نوع	مکان	اجباری	توضیح
agent_id	عدد صحیح	path	بله	شناسه دستیار که باید حذف شود.

نمونه فراخوانی (cURL)

curl --location 'https://app.houshyar24.ir/api/v1/b2b/agents/1/' \
--header 'Authorization: Token <your-token>' \
--data ''

---

پاسخ موفق (200)

{
    "id": 1,
    "name": "My Agent",
    "logo": null,
    "type": "agent",
    "status": "ready",
    "knowledge_base": [],
    "llm_name": "gpt-4o-mini",
    "llm_provider": 8,
    "tools": [
        {
            "category": "سرچ تست",
            "uuid": "5988772b-66ac-47f8-9b80-2bd6fa08db7d",
            "is_active": true
        },
        {
            "category": "تصاویر تست",
            "uuid": "cfb12e95-77e9-4f9c-8265-de55d09d21ff",
            "is_active": true
        }
    ],
    "description": "An agent for customer service.",
    "files": [],
    "crawls": [],
    "opener": null,
    "config": {},
    "category": null,
    "about_project": null,
    "tone_of_voice": null
}

حذف (DELETE) یک دستیار

این سرویس برای ایجاد یک دستیار جدید استفاده می‌شود. در این درخواست باید اطلاعات دستیار مانند name, llm_provider, tools و description را ارسال کنید.

مسیر سرویس

DELETE /api/v1/b2b/agents/{agent_id}/

---

پارامترهای مسیر (Path Parameters)

نام	نوع	مکان	اجباری	توضیح
agent_id	عدد صحیح	path	بله	شناسه دستیار که باید حذف شود.

---

مثال با CURL

curl --location --request DELETE 'https://app.houshyar24.ir/api/v1/b2b/agents/5647803b-6151-4d43-8617-d1e8f9e407a6/' \
--header 'Authorization: Token <your-token>'

---

پاسخ موفق (204)

در هنگام عملیات موفق یک جواب با کد 204 ارسال می شود.