ساخت Agent هوش مصنوعی روی VPS با OpenAI Agents SDK؛ آموزش Tool، Handoff و استقرار حرفه‌ای

با نصب Agents SDK روی یک سرور مجازی یا VPS می‌توانید یک برنامه هوش مصنوعی مستقل داشته باشید که از طریق API به سایت، نرم‌افزار، پنل مدیریتی یا سرویس‌های داخلی شما متصل شود. این برنامه می‌تواند به‌صورت شبانه‌روزی فعال باشد و درخواست‌ها را بدون نیاز به روشن ماندن کامپیوتر شخصی پردازش کند.

در این آموزش، یک Agent پشتیبانی سرور می‌سازیم که دو متخصص دارد: یکی برای سوال‌های فنی سرور و بازی، و دیگری برای سوال‌های مربوط به خدمات و اشتراک‌ها. Agent اصلی درخواست را بررسی می‌کند و در صورت نیاز با قابلیت Handoff آن را به متخصص مناسب منتقل می‌کند. سپس با استفاده از FastAPI، systemd و Nginx برنامه را روی Ubuntu VPS مستقر می‌کنیم.

همچنین ابزارهای Function Tool، کنترل دسترسی، Guardrails، ذخیره تاریخچه گفتگو، Tracing، مدیریت API Key، محدودیت منابع و تست‌های ضروری قبل از انتشار را بررسی خواهیم کرد.

OpenAI Agents SDK چیست و چه کاربردی دارد؟

OpenAI Agents SDK یک کتابخانه برنامه‌نویسی برای ساخت برنامه‌های عامل‌محور هوش مصنوعی است. یک Agent معمولاً از مدل زبانی، دستورالعمل‌ها، ابزارها و منطق اجرایی تشکیل شده است. برخلاف یک چت‌بات ساده، Agent می‌تواند برای انجام یک کار چند مرحله تصمیم بگیرد، ابزار مناسب را فراخوانی کند و در صورت نیاز کنترل کار را به Agent متخصص دیگری منتقل کند.

در Agents SDK، کلاس Agent برای تعریف رفتار و قابلیت‌ها و Runner برای اجرای گردش کار استفاده می‌شود. SDK در جریان یک Run، ارتباط با مدل، اجرای Toolها و Handoffهای تعریف‌شده را مدیریت می‌کند.

تفاوت Agent با چت‌بات معمولی

چه پروژه‌هایی می‌توان با Agents SDK ساخت؟

• دستیار پشتیبانی فنی هاست و VPS.
• Agent پاسخ‌گویی به سوالات مشتریان فروشگاه.
• دستیار بررسی گزارش‌ها و اطلاعات سازمانی.
• Agent تحلیل تیکت‌ها و ارجاع آن‌ها به واحد مناسب.
• دستیار برنامه‌نویسی متصل به ابزارهای مجاز.
• سیستم چندعاملی برای بررسی، دسته‌بندی و پردازش درخواست‌ها.

نکته مهم این است که Agent فقط به ابزارهایی دسترسی دارد که شما در برنامه برای آن تعریف و فعال می‌کنید. برای مثال، تعریف یک Tool خواندن اطلاعات با اعطای دسترسی کامل SSH به سرور تفاوت زیادی دارد.

معماری اجرای Agent هوش مصنوعی روی VPS چگونه است؟

در این آموزش، VPS وظیفه دریافت درخواست‌های کاربران، مدیریت منطق Agent، اجرای ابزارهای محلی و ذخیره وضعیت گفتگو را بر عهده دارد. پردازش مدل زبانی از طریق OpenAI API انجام می‌شود.

مسیر پردازش یک درخواست

1. کاربر درخواست خود را از سایت یا نرم‌افزار ارسال می‌کند.
2. Nginx درخواست HTTPS را دریافت کرده و به FastAPI منتقل می‌کند.
3. FastAPI احراز هویت و اعتبارسنجی اولیه را انجام می‌دهد.
4. Runner اجرای Agent اصلی را آغاز می‌کند.
5. Agent در صورت نیاز Function Tool را فراخوانی می‌کند یا کار را به متخصص می‌سپارد.
6. نتیجه نهایی به کاربر بازگردانده و تاریخچه گفتگو ذخیره می‌شود.

در این معماری، مدل زبانی مستقیماً روی CPU یا GPU سرور مجازی اجرا نمی‌شود. بنابراین برای یک Agent مبتنی بر API، معمولاً نیازی به GPU روی VPS ندارید؛ مگر آنکه خودتان مدل، پردازش تصویر یا سرویس محاسباتی دیگری را نیز به‌صورت محلی اجرا کنید.

آیا Agent با بسته شدن مرورگر متوقف می‌شود؟

خیر. اگر برنامه را به‌صورت یک سرویس پایدار روی VPS مستقر کنید، بسته شدن مرورگر یا خاموش شدن کامپیوتر شخصی باعث توقف سرویس نمی‌شود.

البته این موضوع به معنی ادامه خودکار هر درخواست طولانی بعد از قطع ارتباط نیست. برای کارهای طولانی و قابل بازیابی پس از Restart باید از صف کار، ذخیره وضعیت اجرایی یا زیرساخت اجرای پایدار استفاده کنید.

آخرین نسخه OpenAI Agents SDK و پیش‌نیازهای نصب

در تاریخ ۳ نوامبر ۲۰۲۶، آخرین نسخه پایدار Python SDK در صفحه رسمی انتشارها، openai-agents 0.24.0 است. این نسخه در ۱۵ اکتبر ۲۰۲۶ منتشر شده است.

برای مشاهده انتشارهای بعدی، صفحه GitHub Releases پروژه OpenAI Agents SDK را بررسی کنید.

ابزارهای مورد استفاده در این پروژه

برای استقرار چندکاربره با درخواست‌های هم‌زمان زیاد، می‌توان به‌جای SQLite از پایگاه داده یا Session Backend اشتراکی مانند Redis و SQLAlchemySession استفاده کرد. در این مقاله ابتدا یک نمونه ساده و قابل توسعه برای یک اپراتور یا محیط آزمایشی می‌سازیم.

برای ساخت Agent با OpenAI Agents SDK چه VPS مناسبی است؟

در معماری مبتنی بر OpenAI API، VPS مدل زبانی بزرگ را اجرا نمی‌کند؛ بنابراین منابع موردنیاز آن بیشتر به تعداد درخواست‌های هم‌زمان، تعداد ابزارها، پردازش فایل‌ها و پایگاه داده بستگی دارد.

این اعداد پیشنهاد اولیه برای برنامه Python هستند و حداقل رسمی OpenAI Agents SDK محسوب نمی‌شوند.

اگر Agent شما فقط درخواست را به API ارسال کرده و پاسخ را برمی‌گرداند، ارتقای CPU همیشه باعث افزایش محسوس سرعت پاسخ مدل نمی‌شود. اما اگر ابزارهای محلی پردازش فایل، جست‌وجوی پایگاه داده یا کارهای محاسباتی سنگین انجام می‌دهند، CPU و RAM بیشتر می‌توانند مفید باشند.

اهمیت اتصال اینترنت سرور

VPS باید بتواند به سرویس‌های OpenAI API متصل شود. پایداری شبکه، DNS و ارتباط HTTPS برای اجرای برنامه ضروری است.

برای محیط عملیاتی، پیش از انتخاب موقعیت سرور، دسترسی مجاز و پایدار به API، محل استقرار کاربران و الزامات امنیت داده را بررسی کنید.

دریافت OpenAI API Key برای اجرای Agent

برای استفاده از مدل‌های OpenAI، باید API Key معتبر داشته باشید. حساب ChatGPT و اعتبار مصرف OpenAI API دو بخش جداگانه هستند؛ داشتن اشتراک ChatGPT به‌تنهایی به معنی داشتن اعتبار API برای برنامه شما نیست.

مرحله اول: ورود به پلتفرم API

وارد OpenAI API Platform شوید و پروژه موردنظر خود را انتخاب یا ایجاد کنید.

مرحله دوم: ایجاد کلید

از بخش مدیریت API Keys یک کلید مناسب برای پروژه ایجاد کنید. بهتر است از کلید اختصاصی پروژه با سطح دسترسی محدود استفاده کنید و آن را میان چند سرویس نامرتبط به اشتراک نگذارید.

برای ساخت کلید به صفحه مدیریت OpenAI API Keys مراجعه کنید.

مرحله سوم: مدیریت اعتبار مصرف

برای اجرای درخواست‌های واقعی باید امکان پرداخت یا اعتبار API متناسب با وضعیت حساب خود داشته باشید. میزان مصرف به مدل انتخاب‌شده، تعداد درخواست‌ها، طول پیام‌ها و تعداد فراخوانی Tool یا Handoff بستگی دارد.

هشدار امنیتی: هرگز API Key را داخل کد JavaScript مرورگر، مخزن عمومی Git، فایل HTML سایت یا پاسخ Agent قرار ندهید. کلید باید در سمت سرور و خارج از کد برنامه نگهداری شود.

مرحله اول: نصب Python و OpenAI Agents SDK روی Ubuntu VPS

ابتدا با SSH به VPS متصل شوید. دستورهای این بخش برای Ubuntu 24.04 و کاربری دارای دسترسی sudo نوشته شده‌اند.

به‌روزرسانی فهرست بسته‌ها

sudo apt update
sudo apt install -y python3 python3-venv python3-pip curl ca-certificates nginx

بررسی نسخه Python

python3 --version

در نصب معمول Ubuntu 24.04، نسخه Python برابر 3.12 است.

ساخت کاربر مخصوص Agent

بهتر است سرویس هوش مصنوعی را با کاربر root اجرا نکنید. برای پروژه یک حساب مستقل ایجاد می‌کنیم:

sudo useradd --system --create-home \
--home-dir /opt/iranica-agent \
--shell /usr/sbin/nologin aiagent

این دستور برای نصب جدید است. اگر کاربر یا مسیر موردنظر از قبل وجود دارد، پیش از اجرای مجدد وضعیت آن را بررسی کنید.

ساخت پوشه داده‌ها

sudo install -d -o aiagent -g aiagent -m 750 \
/opt/iranica-agent /var/lib/iranica-agent

ایجاد محیط مجازی Python

sudo -u aiagent python3 -m venv /opt/iranica-agent/.venv

استفاده از محیط مجازی باعث می‌شود کتابخانه‌های پروژه با بسته‌های سیستمی Python تداخل نداشته باشند.

نصب نسخه مشخص Agents SDK

sudo -u aiagent /opt/iranica-agent/.venv/bin/python -m pip install --upgrade pip

sudo -u aiagent /opt/iranica-agent/.venv/bin/pip install \
"openai-agents==0.24.0" fastapi uvicorn

با مشخص کردن نسخه SDK، کدهای این راهنما به نسخه بررسی‌شده وابسته می‌شوند. برای محیط Production بهتر است پس از تست، نسخه سایر وابستگی‌ها را نیز در فایل قفل وابستگی ثبت کنید.

بررسی نسخه نصب‌شده

/opt/iranica-agent/.venv/bin/pip show openai-agents

در خروجی باید نسخه نصب‌شده و مشخصات پکیج نمایش داده شود.

مرحله دوم: ساخت اولین Agent با Python

برای درک ساختار SDK، ابتدا یک Agent ساده تعریف می‌کنیم. بعداً همین مفهوم را در یک پروژه کامل FastAPI به کار خواهیم برد.

فایل first_agent.py را در پوشه پروژه ایجاد کنید:

from agents import Agent, Runner
import asyncio

agent = Agent(
    name="VPS Assistant",
    model="gpt-6-luna",
    instructions=(
        "You are a helpful VPS support assistant. "
        "Answer in Persian. Explain technical topics clearly."
    ),
)

async def main():
    result = await Runner.run(
        agent,
        "تفاوت VPS و هاست اشتراکی چیست؟"
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

در این نمونه سه بخش اصلی وجود دارد:

• Agent: نام، مدل و دستورالعمل‌های دستیار را تعریف می‌کند.
• Runner.run: درخواست را به جریان اجرای Agent ارسال می‌کند.
• final_output: پاسخ نهایی تولیدشده را برمی‌گرداند.

در این مقاله از مدل gpt-6-luna برای نمونه سبک استفاده می‌کنیم. این شناسه طبق فهرست فعلی مدل‌های OpenAI API برای کارهای کم‌هزینه و پرتعداد ارائه شده است. در صورت نیاز می‌توانید مدل را به گزینه سازگار دیگری مانند gpt-6.1-sol تغییر دهید.

برای اجرای این فایل، ابتدا باید متغیر OPENAI_API_KEY را در محیط اجرای برنامه تنظیم کرده باشید. در بخش استقرار نهایی، روش امن‌تر نگهداری آن در EnvironmentFile را بررسی می‌کنیم.

مرحله سوم: ساخت Function Tool برای Agent

یکی از مهم‌ترین قابلیت‌های Agents SDK امکان تعریف تابع Python به‌عنوان Tool است. مدل می‌تواند با توجه به درخواست کاربر تصمیم بگیرد چه زمانی از ابزار استفاده کند.

برای مثال، یک Agent پشتیبانی سرور ممکن است لازم داشته باشد پورت پیش‌فرض بازی‌های مشخص را از یک منبع تعریف‌شده دریافت کند.

نمونه Function Tool برای پورت بازی‌ها

from typing import Literal
from agents import Agent, Runner
from agents.decorators import tool

@tool
def get_game_port(
    game: Literal["minecraft", "cs2", "beammp"]
) -> str:
    """Return common default game ports for a supported game."""
    ports = {
        "minecraft": "Minecraft Java: 25565/TCP",
        "cs2": "CS2: commonly 27015/UDP",
        "beammp": "BeamMP: 30814/TCP and UDP",
    }
    return ports[game]

agent = Agent(
    name="Game Server Assistant",
    model="gpt-6-luna",
    instructions="Answer in Persian. Use the tool for game ports.",
    tools=[get_game_port],
)

در این نمونه، دکوراتور tool تابع Python را به یک ابزار قابل فراخوانی برای Agent تبدیل می‌کند. SDK از نوع پارامترها و توضیحات تابع برای تعریف ساختار ورودی ابزار استفاده می‌کند.

عبارت Literal نیز ورودی ابزار را به نام بازی‌های مشخص محدود می‌کند. به این ترتیب ابزار نمی‌تواند با هر نام یا پارامتر دلخواهی اجرا شود.

آیا Tool همان اجرای دستور SSH است؟

خیر. Tool می‌تواند صرفاً یک تابع خواندنی باشد. در نمونه بالا هیچ اتصال SSH، تغییر فایل یا عملیات اجرایی روی سرور انجام نمی‌شود.

اگر بخواهید یک Tool واقعی برای بررسی وضعیت سرویس، دیتابیس یا پنل بسازید، باید احراز هویت، مجوز کاربر، اعتبارسنجی ورودی و محدودیت دسترسی را داخل همان ابزار پیاده‌سازی کنید.

دادن دسترسی مستقیم و نامحدود Shell به Agent برای اجرای هر دستور دلخواه، الگوی امنی برای سرویس عمومی نیست.

مرحله چهارم: ساخت Agentهای متخصص و Handoff

گاهی بهتر است تمام وظایف را به یک Agent نسپارید. برای مثال، دستیار پاسخ‌گویی اولیه می‌تواند سوال‌های فنی را به Agent متخصص شبکه و سوال‌های اشتراک را به Agent متخصص خدمات منتقل کند.

این انتقال در Agents SDK با مفهوم Handoff انجام می‌شود.

Handoff چگونه عمل می‌کند؟

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

نمونه تعریف Handoff

from agents import Agent

technical_agent = Agent(
    name="Technical Specialist",
    model="gpt-6-luna",
    handoff_description="Handles VPS, Linux and game server issues",
    instructions="Answer technical questions in Persian.",
)

sales_agent = Agent(
    name="Services Specialist",
    model="gpt-6-luna",
    handoff_description="Handles plans, subscriptions and billing questions",
    instructions="Answer service questions in Persian.",
)

triage_agent = Agent(
    name="Support Router",
    model="gpt-6-luna",
    instructions="Route questions to the correct specialist.",
    handoffs=[technical_agent, sales_agent],
)

برای اجرای گردش کار از Runner.run استفاده می‌شود. نتیجه نهایی همچنین مشخص می‌کند آخرین Agent اجراشده کدام بوده است.

تفاوت Handoff و Agent as Tool

اگر Agent اصلی باید چند متخصص را فراخوانی کند و خودش پاسخ نهایی را ترکیب کند، روش Agent as Tool مناسب‌تر است.

نمونه تبدیل متخصص به Tool:

manager_agent = Agent(
    name="Support Manager",
    model="gpt-6-luna",
    instructions="Use specialists when necessary and write the final answer.",
    tools=[
        technical_agent.as_tool(
            tool_name="technical_advice",
            tool_description="Get technical VPS advice",
        )
    ],
)

این دو روش را می‌توان در معماری‌های بزرگ‌تر ترکیب کرد؛ اما هر متخصص و هر Tool باید محدوده مسئولیت مشخصی داشته باشد.

مرحله پنجم: افزودن Guardrails برای کنترل ورودی و خروجی

وقتی Agent از طریق API در دسترس کاربران قرار می‌گیرد، نمی‌توان فرض کرد همه ورودی‌ها معتبر، بی‌خطر یا مرتبط با کاربرد برنامه هستند.

Guardrails در Agents SDK برای بررسی ورودی‌ها و خروجی‌های Agent طراحی شده‌اند. برای مثال، می‌توانید درخواست‌هایی را که شامل اطلاعات محرمانه هستند شناسایی کنید یا قبل از نمایش پاسخ، آن را از نظر وجود الگوهای حساس بررسی کنید.

سه سطح مهم کنترل

• Input Guardrail: بررسی درخواست هنگام شروع اجرای Agent.
• Output Guardrail: بررسی پاسخ نهایی پیش از تحویل به کاربر.
• Tool Guardrail: کنترل ورودی یا خروجی فراخوانی‌های Function Tool.

این سه سطح دقیقاً یکسان عمل نمی‌کنند. Input Guardrail در ابتدای زنجیره اجرا می‌شود و Output Guardrail روی خروجی Agent نهایی اعمال می‌شود. Tool Guardrail برای اجرای ابزارهای تابعی کاربرد دارد.

تفاوت Guardrail موازی و مسدودکننده

در حالت پیش‌فرض، Input Guardrail می‌تواند هم‌زمان با اجرای Agent بررسی شود. این روش تأخیر کمتری دارد؛ اما ممکن است Agent پیش از رد شدن درخواست، بخشی از پردازش یا اجرای Tool را آغاز کرده باشد.

برای ورودی‌هایی که نباید پیش از بررسی به ابزارها برسند، استفاده از حالت blocking با run_in_parallel=False مناسب‌تر است.

در پروژه عملی این مقاله، یک Guardrail ساده برای شناسایی الگوی API Key و Private Key پیاده‌سازی می‌کنیم.

محدودیت مهم: این کنترل نمونه صرفاً چند الگوی مشخص را بررسی می‌کند و سیستم کامل تشخیص اطلاعات محرمانه یا Prompt Injection نیست. برای سرویس عمومی، کنترل‌های امنیتی باید در لایه API، ابزارها و سیاست‌های دسترسی نیز اجرا شوند.

مرحله ششم: حفظ State و تاریخچه گفتگو در Agent

اگر Agent فقط یک پیام را دریافت و پاسخ آن را برگرداند، در درخواست بعدی ممکن است اطلاعات گفتگوی قبلی در دسترس نباشد. برای پشتیبانی چندمرحله‌ای، باید وضعیت گفتگو حفظ شود.

Agents SDK چند روش برای مدیریت تاریخچه دارد.

نمونه ذخیره گفتگو با SQLiteSession

from agents import SQLiteSession, Runner

session = SQLiteSession(
    "conversation_001",
    "conversations.db"
)

result = await Runner.run(
    triage_agent,
    "سرور Minecraft من وصل نمی‌شود",
    session=session,
)

result = await Runner.run(
    triage_agent,
    "پورت پیش‌فرض آن چند است؟",
    session=session,
)

session.close()

در این مثال، دو درخواست به یک Session مرتبط هستند و SDK تاریخچه همان گفتگو را مدیریت می‌کند.

با ذخیره SQLite روی دیسک، تاریخچه می‌تواند پس از Restart برنامه نیز در دسترس بماند؛ به شرط آنکه فایل پایگاه داده حذف نشده باشد.

Session ID رمز عبور نیست

شناسه Session فقط برای انتخاب تاریخچه گفتگو استفاده می‌شود و به‌تنهایی مالکیت کاربر را اثبات نمی‌کند. در برنامه چندکاربره باید هر Session به شناسه کاربر احراز هویت‌شده متصل باشد.

همچنین در یک اجرای Runner نباید Session را بدون بررسی سازگاری، هم‌زمان با previous_response_id یا conversation_id به کار ببرید؛ این‌ها راهبردهای متفاوت مدیریت وضعیت هستند.

تفاوت حافظه گفتگو و اجرای پایدار

ذخیره تاریخچه به این معنی نیست که Agent پس از خاموش شدن VPS می‌تواند یک عملیات نیمه‌تمام را به‌صورت خودکار ادامه دهد.

برای کارهای طولانی، تاییدهای انسانی و عملیات چندمرحله‌ای قابل بازیابی، باید علاوه بر Session، وضعیت اجرایی و زیرساخت مناسب برای Resume یا Durable Execution طراحی شود.

مرحله هفتم: ساخت پروژه کامل Agent هوش مصنوعی

اکنون مفاهیم اصلی را در یک برنامه واحد ترکیب می‌کنیم. پروژه ما دارای این قابلیت‌ها است:

• دریافت درخواست از طریق HTTP API.
• احراز هویت با توکن مخصوص برنامه.
• یک Agent اصلی برای تشخیص نوع سوال.
• دو Agent متخصص برای پشتیبانی فنی و خدمات.
• یک Function Tool خواندنی برای اطلاعات پورت بازی‌ها.
• Guardrail ورودی و خروجی.
• ذخیره تاریخچه گفتگو در SQLite.
• Tracing با کاهش ثبت داده‌های حساس.
• محدود کردن تعداد مراحل اجرای Agent.

برای نمونه آموزشی، درخواست‌ها را در یک Worker و به‌صورت کنترل‌شده پردازش می‌کنیم. این طراحی برای شروع و آزمایش مناسب است، اما برای سامانه عمومی چندکاربره با ظرفیت بالا به توسعه بیشتری نیاز دارد.

ساخت فایل app.py

فایل پروژه را ایجاد کنید:

sudo nano /opt/iranica-agent/app.py

کد کامل زیر را قرار دهید:

import asyncio
import hashlib
import logging
import os
import secrets

from typing import Literal

from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel, Field

from agents import (
    Agent,
    Runner,
    RunConfig,
    SQLiteSession,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    OutputGuardrailTripwireTriggered,
    MaxTurnsExceeded,
)

from agents.decorators import (
    tool,
    input_guardrail,
    output_guardrail,
)

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("iranica-agent")

MODEL = os.getenv("AGENT_MODEL", "gpt-6-luna")
DB_PATH = os.getenv(
    "SESSION_DB",
    "/var/lib/iranica-agent/conversations.db",
)

API_TOKEN = os.environ["AGENT_API_TOKEN"]
OPENAI_KEY = os.environ["OPENAI_API_KEY"]

app = FastAPI(
    title="IranicaServer Agent API",
    docs_url=None,
    redoc_url=None,
)

# Starter deployment: serialize requests in one worker.
# For multi-user production, use an authenticated
# shared session backend and per-conversation locking.
run_lock = asyncio.Lock()


@tool
def get_game_port(
    game: Literal["minecraft", "cs2", "beammp"]
) -> str:
    """Return typical default game ports from a fixed guide."""
    ports = {
        "minecraft": "Minecraft Java uses 25565/TCP by default.",
        "cs2": "CS2 commonly uses 27015/UDP.",
        "beammp": "BeamMP uses 30814/TCP and UDP by default.",
    }
    return ports[game]


@input_guardrail(run_in_parallel=False)
async def protect_input(ctx, agent, input):
    content = str(input)

    detected_secret = (
        "sk-" in content
        or "-----BEGIN PRIVATE KEY-----" in content
    )

    return GuardrailFunctionOutput(
        output_info={"secret_pattern": detected_secret},
        tripwire_triggered=detected_secret,
    )


@output_guardrail
async def protect_output(ctx, agent, output):
    content = str(output)

    detected_secret = (
        "sk-" in content
        or "-----BEGIN PRIVATE KEY-----" in content
    )

    return GuardrailFunctionOutput(
        output_info={"secret_pattern": detected_secret},
        tripwire_triggered=detected_secret,
    )


technical_agent = Agent(
    name="Technical Specialist",
    model=MODEL,
    handoff_description=(
        "Handles Linux, VPS networking, game servers, "
        "firewalls and connectivity problems."
    ),
    instructions=(
        "You are a technical VPS and gaming support specialist. "
        "Answer in Persian. Give safe troubleshooting steps. "
        "Do not claim to have accessed a real server. "
        "Use the port guide when useful. "
        "Never request passwords or API keys."
    ),
    tools=[get_game_port],
    output_guardrails=[protect_output],
)


services_agent = Agent(
    name="Services Specialist",
    model=MODEL,
    handoff_description=(
        "Handles hosting plans, subscriptions, "
        "service selection and billing questions."
    ),
    instructions=(
        "You help users understand hosting and VPS services. "
        "Answer in Persian. Do not invent live prices, "
        "account balances, invoices or subscription status. "
        "If account-specific data is needed, explain that "
        "an authenticated integration is required."
    ),
    output_guardrails=[protect_output],
)


triage_agent = Agent(
    name="Support Router",
    model=MODEL,
    instructions=(
        "You are the first-line support agent. "
        "Answer simple questions in Persian. "
        "Transfer technical questions to Technical Specialist. "
        "Transfer sales and billing questions to "
        "Services Specialist. "
        "Never claim that an action was performed "
        "unless a verified tool actually performed it."
    ),
    handoffs=[technical_agent, services_agent],
    tools=[get_game_port],
    input_guardrails=[protect_input],
    output_guardrails=[protect_output],
)


class ChatRequest(BaseModel):
    session_id: str = Field(
        min_length=8,
        max_length=64,
        pattern=r"^[A-Za-z0-9_-]+$",
    )
    message: str = Field(
        min_length=1,
        max_length=3000,
    )


@app.get("/healthz")
async def health():
    return {"ok": True}


@app.post("/v1/chat")
async def chat(
    request: ChatRequest,
    x_agent_token: str | None = Header(default=None),
):
    if (
        x_agent_token is None
        or not secrets.compare_digest(x_agent_token, API_TOKEN)
    ):
        raise HTTPException(
            status_code=401,
            detail="Unauthorized",
        )

    session = SQLiteSession(request.session_id, DB_PATH)

    group_id = hashlib.sha256(
        request.session_id.encode("utf-8")
    ).hexdigest()[:16]

    try:
        async with run_lock:
            result = await Runner.run(
                triage_agent,
                request.message,
                session=session,
                max_turns=8,
                run_config=RunConfig(
                    workflow_name="IranicaServer VPS Support",
                    group_id=group_id,
                    trace_include_sensitive_data=False,
                ),
            )

        return {
            "session_id": request.session_id,
            "agent": result.last_agent.name,
            "answer": str(result.final_output),
        }

    except (
        InputGuardrailTripwireTriggered,
        OutputGuardrailTripwireTriggered,
    ):
        raise HTTPException(
            status_code=400,
            detail="Request blocked by guardrail",
        )

    except MaxTurnsExceeded:
        raise HTTPException(
            status_code=422,
            detail="Agent exceeded the permitted turn limit",
        )

    except Exception:
        logger.exception("Agent execution failed")
        raise HTTPException(
            status_code=502,
            detail="Agent service temporarily unavailable",
        )

    finally:
        session.close()

این کد دقیقاً چه کاری انجام می‌دهد؟

در این برنامه، درخواست ابتدا وارد FastAPI می‌شود. توکن دریافتی با مقدار تعریف‌شده در سرور مقایسه می‌شود و اگر معتبر نباشد، پاسخ HTTP 401 بازمی‌گردد.

در درخواست معتبر، تاریخچه گفتگو براساس session_id از SQLite خوانده می‌شود و Runner اجرای triage_agent را آغاز می‌کند.

اگر سوال فنی باشد، Agent اصلی می‌تواند آن را به Technical Specialist منتقل کند. اگر درخواست درباره خدمات یا اشتراک باشد، Services Specialist ادامه کار را انجام می‌دهد.

برای سوال‌های مربوط به پورت بازی‌ها نیز ابزار get_game_port در اختیار Agent قرار دارد.

در پایان، نام Agent پاسخ‌دهنده و متن پاسخ به‌صورت JSON به درخواست‌کننده بازگردانده می‌شود.

محدودیت مهم نمونه

این کد برای یک اپراتور یا محیط آزمایشی دارای یک توکن مشترک طراحی شده است. در آن، درخواست‌ها با یک Lock سراسری به‌ترتیب اجرا می‌شوند تا در نمونه تک‌فرآیندی، عملیات هم‌زمان باعث اختلال در تاریخچه گفتگو نشود.

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

همچنین Guardrail این نمونه صرفاً چند الگوی مشخص را بررسی می‌کند و نباید به‌عنوان سامانه جامع DLP یا حفاظت کامل در برابر Prompt Injection معرفی شود.

مرحله هشتم: ساخت REST API و تنظیم اطلاعات محرمانه

در مرحله قبل، کد برنامه آماده شد. اکنون باید متغیرهای محیطی و کلیدهای موردنیاز را به شکل جداگانه تنظیم کنیم.

ساخت پوشه تنظیمات محرمانه

sudo install -d -o root -g root -m 700 /etc/iranica-agent
sudo nano /etc/iranica-agent/agent.env

مقادیر زیر را قرار دهید:

OPENAI_API_KEY=YOUR_OPENAI_API_KEY
AGENT_API_TOKEN=YOUR_RANDOM_LONG_SECRET
AGENT_MODEL=gpt-6-luna
SESSION_DB=/var/lib/iranica-agent/conversations.db
OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false

دو مقدار YOUR_OPENAI_API_KEY و YOUR_RANDOM_LONG_SECRET باید با مقادیر واقعی و مستقل جایگزین شوند.

توکن دسترسی به API برنامه، با OpenAI API Key یکسان نیست. یکی برای ارتباط برنامه با OpenAI و دیگری برای جلوگیری از دسترسی غیرمجاز به endpoint شما استفاده می‌شود.

تنظیم مجوز فایل

sudo chown root:root /etc/iranica-agent/agent.env
sudo chmod 600 /etc/iranica-agent/agent.env

systemd می‌تواند این فایل را هنگام راه‌اندازی سرویس بخواند و متغیرها را در اختیار فرآیند Agent قرار دهد.

از قرار دادن API Key در آرگومان‌های خط فرمان، فایل عمومی پروژه یا پیام‌های Log خودداری کنید.

بررسی Syntax کد Python

/opt/iranica-agent/.venv/bin/python -m py_compile \
/opt/iranica-agent/app.py

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

مرحله نهم: اجرای دائمی Agent روی VPS با systemd

اگر برنامه را صرفاً در یک ترمینال اجرا کنید، با بسته شدن نشست یا متوقف شدن فرآیند ممکن است سرویس از دسترس خارج شود.

برای اجرای پایدار از systemd استفاده می‌کنیم تا برنامه هنگام روشن شدن سیستم اجرا شود و در صورت توقف غیرمنتظره، دوباره راه‌اندازی شود.

ساخت سرویس Agent

sudo nano /etc/systemd/system/iranica-agent.service

محتوای زیر را وارد کنید:

[Unit]
Description=IranicaServer OpenAI Agents API
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=aiagent
Group=aiagent
WorkingDirectory=/opt/iranica-agent
EnvironmentFile=/etc/iranica-agent/agent.env

ExecStart=/opt/iranica-agent/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8765 --workers 1

Restart=on-failure
RestartSec=10
TimeoutStopSec=30
UMask=0077

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/iranica-agent

MemoryAccounting=true
CPUAccounting=true

[Install]
WantedBy=multi-user.target

در این تنظیمات، برنامه با کاربر aiagent اجرا می‌شود، فقط روی آدرس 127.0.0.1 گوش می‌دهد و پورت 8765 مستقیماً به اینترنت عمومی منتشر نمی‌شود.

همچنین ProtectSystem و سایر تنظیمات امنیتی دسترسی نوشتن فرآیند را محدود می‌کنند. این تنظیمات باید در صورت اضافه شدن ابزارهای جدید یا مسیرهای ذخیره‌سازی دیگر، دوباره بررسی شوند.

فعال‌سازی سرویس

sudo systemctl daemon-reload
sudo systemctl enable --now iranica-agent
sudo systemctl status iranica-agent --no-pager

تست سلامت محلی

curl http://127.0.0.1:8765/healthz

اگر برنامه به‌درستی اجرا شده باشد، پاسخ زیر دریافت می‌شود:

{"ok":true}

این endpoint فقط نشان می‌دهد برنامه FastAPI فعال است؛ برای تایید کامل سیستم باید یک درخواست واقعی به /v1/chat ارسال کنید.

تست Agent با curl

curl -X POST http://127.0.0.1:8765/v1/chat \
-H "Content-Type: application/json" \
-H "X-Agent-Token: YOUR_RANDOM_LONG_SECRET" \
-d '{
  "session_id": "demo_session_001",
  "message": "پورت پیش‌فرض BeamMP چیست؟"
}'

در یک درخواست موفق، پاسخ JSON شامل session_id، نام Agent پاسخ‌دهنده و متن answer خواهد بود.

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

مرحله دهم: اتصال دامنه و فعال‌سازی HTTPS با Nginx

برای استفاده از Agent در سایت یا نرم‌افزار خارجی، بهتر است API را پشت Reverse Proxy قرار دهید و از HTTPS استفاده کنید.

در این مثال فرض می‌کنیم دامنه‌ای مانند agent.example.com به IPv4 عمومی VPS اشاره می‌کند. این دامنه نمونه است و باید آن را با دامنه واقعی خود جایگزین کنید.

ساخت تنظیمات Nginx

sudo nano /etc/nginx/sites-available/iranica-agent

نمونه تنظیمات اولیه:

server {
    listen 80;
    server_name agent.example.com;

    client_max_body_size 16k;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 10s;
        proxy_read_timeout 180s;
    }
}

این تنظیمات برای مرحله راه‌اندازی HTTP است و قبل از انتشار عمومی باید HTTPS فعال شود. از ارسال توکن دسترسی یا درخواست‌های حساس روی HTTP بدون رمزنگاری خودداری کنید.

فعال‌سازی سایت

sudo ln -s /etc/nginx/sites-available/iranica-agent \
/etc/nginx/sites-enabled/iranica-agent

sudo nginx -t
sudo systemctl reload nginx

اگر فایل یا لینک از قبل موجود است، آن را بدون بررسی جایگزین نکنید.

فعال‌سازی گواهی SSL

برای دریافت گواهی Let’s Encrypt می‌توانید از Certbot استفاده کنید:

sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d agent.example.com

قبل از اجرای Certbot، دامنه باید به سرور اشاره کند و ارتباط ورودی روی پورت موردنیاز اعتبارسنجی گواهی برقرار باشد.

پس از دریافت گواهی، مطمئن شوید درخواست‌های HTTP به HTTPS هدایت می‌شوند و فقط endpointهای موردنیاز در دسترس عمومی قرار دارند.

آیا لازم است پورت 8765 را باز کنیم؟

خیر. در این معماری FastAPI روی 127.0.0.1 گوش می‌دهد و Nginx درخواست‌های عمومی را به آن منتقل می‌کند. بنابراین پورت داخلی 8765 نباید به‌صورت عمومی در Firewall باز شود.

فقط پورت‌های لازم مانند 80 و 443 و دسترسی مدیریتی امن سرور را مطابق سیاست شبکه خود تنظیم کنید.

مرحله یازدهم: Tracing در OpenAI Agents SDK چیست؟

وقتی یک Agent ساده فقط یک پاسخ تولید می‌کند، بررسی خطا نسبتاً آسان است. اما در یک سیستم چندعاملی ممکن است درخواست از Agent اصلی به متخصص منتقل شود، چند Tool اجرا شود و سپس پاسخ نهایی تولید شود.

Tracing به شما کمک می‌کند جریان این مراحل را بررسی کنید.

چه اطلاعاتی در Trace ثبت می‌شود؟

بسته به پیکربندی، Tracing می‌تواند رویدادهای مربوط به اجرای مدل، فراخوانی ابزارها، Handoffها، Guardrailها و زمان اجرای مراحل را ثبت کند.

این اطلاعات برای تشخیص مشکلاتی مانند انتخاب Tool اشتباه، Handoff غیرضروری یا افزایش تعداد فراخوانی مدل کاربرد دارند.

آیا Tracing به‌صورت پیش‌فرض فعال است؟

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

در نمونه این مقاله، مقدار زیر را در RunConfig تنظیم کرده‌ایم:

RunConfig(
    workflow_name="IranicaServer VPS Support",
    trace_include_sensitive_data=False,
)

این گزینه باعث می‌شود برخی داده‌های حساس ورودی و خروجی در Spanهای مربوط به مدل و Tool ذخیره نشوند؛ با این حال، نباید آن را معادل حذف تمام اطلاعات شناسایی‌کننده از همه بخش‌های سیستم دانست.

غیرفعال کردن کامل Tracing

اگر به دلایل سیاست داده یا محرمانگی نمی‌خواهید Tracing انجام شود، می‌توانید در EnvironmentFile مقدار زیر را تنظیم کنید:

OPENAI_AGENTS_DISABLE_TRACING=1

پس از تغییر تنظیمات محیطی، سرویس را Restart کنید.

مشاهده Traceها

برای مشاهده گردش کار و Traceها می‌توانید از بخش Traces در داشبورد OpenAI Platform استفاده کنید، مشروط بر اینکه Tracing فعال و ارسال داده‌ها با موفقیت انجام شده باشد.

راهنمای کامل در مستندات رسمی Tracing ارائه شده است.

مرحله دوازدهم: امنیت Agent هوش مصنوعی روی VPS

وقتی یک Agent به ابزارهای برنامه دسترسی دارد، امنیت آن فقط به محرمانه نگه داشتن API Key محدود نمی‌شود. باید مشخص باشد هر درخواست از چه کاربری دریافت شده، Agent مجاز است چه عملیاتی انجام دهد و هر Tool به چه داده‌هایی دسترسی دارد.

۱. محدود کردن دسترسی ابزارها

برای مثال، یک Agent پشتیبانی معمولی نباید امکان اجرای آزادانه دستورهای Shell، مشاهده فایل‌های محرمانه یا تغییر Firewall سرور را داشته باشد.

اگر Tool مدیریتی نیاز دارید، بهتر است آن را با عملیات دقیق و از پیش تعریف‌شده بسازید؛ برای مثال، بررسی وضعیت یک سرویس مجاز به‌جای دریافت یک دستور دلخواه از مدل.

۲. احراز هویت واقعی کاربران

در کد نمونه از یک توکن مشترک استفاده شده است. این روش برای آزمایش خصوصی یا یک اپراتور مناسب است، نه برای یک سامانه عمومی با کاربران متعدد.

در محصول نهایی، برنامه باید کاربر را با روش مناسب مانند Session امن یا JWT معتبر احراز هویت کند و مالکیت conversation_id یا session_id را در سمت سرور بررسی کند.

۳. محافظت در برابر Prompt Injection

ممکن است متن ورودی کاربر یا اطلاعات دریافتی از یک فایل و وب‌سایت شامل دستورهایی باشد که تلاش می‌کنند رفتار Agent را تغییر دهند.

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

۴. تایید انسانی برای عملیات حساس

اگر Agent قرار است پرداخت انجام دهد، فایل مهمی را حذف کند یا تنظیمات سرور را تغییر دهد، بهتر است قبل از اجرای عملیات تأیید معتبر دریافت شود.

Agents SDK از الگوهای Human-in-the-loop پشتیبانی می‌کند. اما خود برنامه نیز باید مجوز کاربر، محدودیت عملیات و ثبت رویدادهای اجرایی را رعایت کند.

۵. کنترل هزینه و تعداد درخواست‌ها

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

در کد نمونه از max_turns=8 برای محدود کردن مراحل اجرای Runner استفاده شده است. این محدودیت جایگزین Rate Limit سراسری، محدودیت هزینه، Timeouts و کنترل تعداد درخواست کاربران نیست.

۶. امنیت پایگاه داده Session

فایل SQLite ممکن است شامل تاریخچه گفتگو و اطلاعات حساس کاربران باشد. بنابراین باید دسترسی فایل محدود باشد، Backup آن محافظت شود و سیاست نگهداری و حذف اطلاعات تعریف شود.

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

۷. امنیت Toolهای متصل به وب و API

اگر Tool به آدرس اینترنتی دریافت‌شده از کاربر درخواست ارسال می‌کند، باید خطر SSRF و دسترسی ناخواسته به سرویس‌های داخلی VPS را در نظر بگیرید.

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

مرحله سیزدهم: چک‌لیست Production Deployment

اجرای موفق یک Agent در محیط آزمایشی به معنی آماده بودن آن برای پذیرش کاربران عمومی نیست. قبل از انتشار باید چند لایه عملیاتی و امنیتی بررسی شوند.

بررسی‌های ضروری قبل از انتشار

• نسخه SDK و وابستگی‌های Python مشخص و قابل بازتولید باشند.
• API Key و توکن‌های برنامه خارج از مخزن کد ذخیره شوند.
• HTTPS فعال و پورت داخلی FastAPI غیرعمومی باشد.
• احراز هویت، Rate Limiting و محدودیت اندازه درخواست وجود داشته باشد.
• هر Session فقط برای کاربر مجاز قابل دسترسی باشد.
• ابزارها براساس کمترین سطح دسترسی طراحی شده باشند.
• عملیات حساس دارای تأیید معتبر و ثبت رویداد باشند.
• Timeout، Retry و مدیریت خطای سرویس OpenAI بررسی شده باشد.
• تعداد مراحل Runner و هزینه مصرف مدل کنترل شود.
• فایل‌های Session و تنظیمات دارای Backup مناسب باشند.
• داده‌های حساس در Logها و Traces بی‌دلیل ذخیره نشوند.
• تست بار و تست درخواست‌های هم‌زمان انجام شده باشد.
• وضعیت سرویس پس از Restart سیستم بررسی شده باشد.

چرا یک Worker برای نمونه اولیه انتخاب کردیم؟

در این آموزش از SQLiteSession و یک Lock سراسری استفاده کرده‌ایم. بنابراین درخواست‌ها در یک فرآیند به‌ترتیب اجرا می‌شوند.

این روش برای فهم جریان اجرای Agent و راه‌اندازی اولیه مناسب است، اما با افزایش تعداد کاربران می‌تواند به گلوگاه تبدیل شود.

برای مقیاس‌پذیری، باید Session Backend اشتراکی، مدیریت هم‌زمانی در سطح هر گفتگو و Workerهای مستقل را طراحی کنید. راهکارهایی مانند RedisSession یا SQLAlchemySession می‌توانند بخشی از این معماری باشند، اما به‌تنهایی جایگزین کنترل مجوز و قفل‌گذاری مناسب نمی‌شوند.

چگونه وابستگی‌های پروژه را قفل کنیم؟

پس از نصب و تست نسخه‌های سازگار، می‌توانید از محیط مجازی فهرست نسخه‌های دقیق را استخراج کنید:

sudo -u aiagent /opt/iranica-agent/.venv/bin/pip freeze \
| sudo tee /opt/iranica-agent/requirements.lock

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

مانیتورینگ سرویس با journalctl

sudo journalctl -u iranica-agent -n 100 --no-pager

برای مشاهده زنده رخدادها:

sudo journalctl -u iranica-agent -f

هنگام عیب‌یابی، اطلاعات احراز هویت و پیام‌های محرمانه کاربران را بدون نیاز در Log ثبت نکنید.

تست‌های کاربردی بعد از استقرار

هزینه اجرای OpenAI Agents SDK روی VPS چگونه محاسبه می‌شود؟

برای ساخت Agent مبتنی بر API معمولاً دو دسته هزینه اصلی وجود دارد: هزینه میزبانی برنامه روی VPS و هزینه مصرف سرویس OpenAI API.

هزینه VPS

VPS منابع لازم برای اجرای Python، FastAPI، پایگاه داده و ابزارهای محلی را فراهم می‌کند.

اگر پردازش‌های محلی سبک باشند، معمولاً یک سرور کوچک برای شروع کافی است. اما برای تعداد کاربران بیشتر یا Toolهای محاسباتی، باید منابع واقعی را اندازه‌گیری و متناسب با آن ارتقا دهید.

هزینه OpenAI API

هزینه API به مدل، تعداد توکن‌های ورودی و خروجی، تعداد فراخوانی‌ها و ابزارهای مورد استفاده بستگی دارد.

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

بنابراین تعداد پیام‌های کاربران به‌تنهایی معیار کافی برای تخمین مصرف نیست.

چگونه هزینه Agent را کاهش دهیم؟

• مدل مناسب پیچیدگی وظیفه را انتخاب کنید.
• برای سوال‌های ساده از Agent و مدل سبک‌تر استفاده کنید.
• تعداد Handoffهای غیرضروری را کاهش دهید.
• تاریخچه گفتگو را مدیریت کنید تا بی‌دلیل طولانی نشود.
• برای اطلاعات قطعی از Function Tool استفاده کنید.
• محدودیت تعداد مراحل و درخواست‌ها تعریف کنید.
• مصرف API را در داشبورد و سامانه مانیتورینگ بررسی کنید.

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

آیا برای Agent هوش مصنوعی، VPS قوی‌تر لازم است؟

اگر Agent شما فقط یک واسط بین کاربران و OpenAI API باشد، افزایش RAM یا CPU به‌تنهایی باعث قوی‌تر شدن مدل هوش مصنوعی نمی‌شود.

اما اگر برنامه شامل پایگاه داده، چند Worker، پردازش اسناد، ابزارهای محلی، تبدیل فایل یا سرویس‌های جانبی باشد، منابع بیشتر می‌توانند ظرفیت پردازش هم‌زمان و پایداری برنامه را بهبود دهند.

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

خطاهای رایج هنگام اجرای OpenAI Agents SDK روی VPS

۱. خطای ModuleNotFoundError: No module named ‘agents’

این خطا معمولاً نشان می‌دهد پکیج در محیط Python فعال نصب نشده یا برنامه با Interpreter اشتباه اجرا شده است.

برای بررسی، از Python محیط مجازی استفاده کنید:

/opt/iranica-agent/.venv/bin/pip show openai-agents

۲. خطای OpenAI API Key

اگر OPENAI_API_KEY تنظیم نشده یا نامعتبر باشد، درخواست واقعی به مدل با خطای احراز هویت مواجه می‌شود.

وجود متغیر را در EnvironmentFile بررسی کنید، اما مقدار کلید واقعی را در Log یا خروجی عمومی نمایش ندهید.

۳. خطای HTTP 401 هنگام فراخوانی API Agent

اگر درخواست به /v1/chat با وضعیت 401 پاسخ داده شود، احتمالاً مقدار X-Agent-Token ارسال نشده یا با توکن تنظیم‌شده در سرور مطابقت ندارد.

توجه کنید این توکن با OpenAI API Key متفاوت است.

۴. خطای HTTP 429 یا محدودیت مصرف

این خطا می‌تواند از محدودیت‌های استفاده API یا سیاست Rate Limit برنامه شما ناشی شود.

قبل از Retry، منشأ خطا را شناسایی کنید. برای خطاهای موقت می‌توان از سیاست Backoff و Retry کنترل‌شده استفاده کرد، اما تکرار بی‌محدودیت درخواست‌ها ممکن است هزینه و فشار بیشتری ایجاد کند.

۵. Agent در Handoff اشتباه می‌کند

توضیحات handoff_description و instructions متخصص‌ها را بررسی کنید. اگر حوزه مسئولیت دو متخصص مبهم یا هم‌پوشان باشد، Agent اصلی ممکن است درخواست را به متخصص نامناسب منتقل کند.

با استفاده از Traceها و مجموعه‌ای از درخواست‌های آزمایشی می‌توانید رفتار ارجاع را ارزیابی کنید.

۶. Guardrail درخواست را مسدود می‌کند

اگر ورودی یا خروجی با شرط تعریف‌شده در Guardrail تطابق داشته باشد، SDK می‌تواند استثنای مربوط به Tripwire را ایجاد کند.

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

۷. تاریخچه گفتگو پس از Restart از بین می‌رود

اگر از Session حافظه‌ای استفاده کرده باشید، داده‌ها پس از بسته شدن فرآیند باقی نمی‌مانند.

برای ذخیره پایدار، SQLiteSession را با مسیر فایل مشخص یا یک Backend پایدار دیگر تنظیم کنید. همچنین مطمئن شوید کاربر سرویس به مسیر ذخیره‌سازی دسترسی نوشتن دارد.

۸. خطای Permission denied در SQLite

مسیر SESSION_DB و سطح دسترسی پوشه داده‌ها را بررسی کنید.

sudo ls -ld /var/lib/iranica-agent
sudo systemctl status iranica-agent --no-pager

۹. سرویس systemd مدام Restart می‌شود

ممکن است مسیر Python اشتباه باشد، یکی از متغیرهای ضروری تنظیم نشده باشد یا برنامه هنگام Import خطا بدهد.

برای تشخیص علت:

sudo journalctl -u iranica-agent -n 100 --no-pager

۱۰. خطای 502 Bad Gateway در Nginx

اگر Nginx نتواند به FastAPI متصل شود، ممکن است سرویس متوقف باشد یا پورت و آدرس upstream اشتباه تنظیم شده باشد.

ابتدا پاسخ محلی /healthz را بررسی کنید و سپس تنظیمات Nginx را با دستور nginx -t آزمایش کنید.

۱۱. پاسخ Agent کند است

تأخیر می‌تواند به مدل انتخاب‌شده، تعداد مراحل Agent، Handoffها، زمان پاسخ Tool و کیفیت شبکه وابسته باشد.

Tracing کمک می‌کند مشخص کنید کدام مرحله زمان بیشتری مصرف کرده است. همچنین باید شرایط محدودیت API و فشار روی سرویس‌های محلی را بررسی کنید.

۱۲. Agent پس از اجرای یک Tool متوقف می‌شود

ممکن است Tool خطا داده باشد، Guardrail فعال شده باشد یا Runner به محدودیت max_turns رسیده باشد.

لاگ برنامه و Traceهای مرتبط را بررسی کنید و برای Toolهای واقعی، خطاهای قابل پیش‌بینی را به‌صورت کنترل‌شده مدیریت کنید.

سوالات متداول درباره OpenAI Agents SDK روی VPS

OpenAI Agents SDK چیست؟

یک کتابخانه برای ساخت برنامه‌های Agentمحور است که قابلیت‌هایی مانند Tool، Handoff، Guardrails، Sessions و Tracing را فراهم می‌کند.

آیا می‌توان OpenAI Agents SDK را روی سرور مجازی نصب کرد؟

بله. می‌توانید آن را همراه Python روی یک VPS لینوکسی نصب کرده و برنامه خود را از طریق API در دسترس سرویس‌های دیگر قرار دهید.

برای اجرای Agent روی VPS به کارت گرافیک نیاز داریم؟

اگر از OpenAI API استفاده می‌کنید و مدل را به‌صورت محلی اجرا نمی‌کنید، معمولاً GPU برای خود برنامه Agent ضروری نیست.

آیا برای OpenAI Agents SDK باید API Key بخریم؟

برای فراخوانی مدل‌های OpenAI به API Key معتبر و اعتبار مصرف نیاز دارید. هزینه مصرف API مستقل از هزینه VPS و اشتراک ChatGPT است.

آخرین نسخه Python OpenAI Agents SDK چیست؟

تا زمان بررسی این مقاله در ۳ نوامبر ۲۰۲۶، آخرین نسخه پایدار منتشرشده 0.24.0 است. برای نسخه‌های جدیدتر، صفحه رسمی GitHub Releases را بررسی کنید.

آیا Agents SDK فقط با Python کار می‌کند؟

خیر. علاوه بر SDK پایتون، نسخه JavaScript و TypeScript نیز در اکوسیستم Agents SDK وجود دارد. این آموزش بر پیاده‌سازی Python تمرکز دارد.

Function Tool در Agent چیست؟

تابع یا ابزاری است که Agent می‌تواند در جریان پاسخ‌گویی فراخوانی کند؛ مانند دریافت داده از یک منبع معتبر یا اجرای عملیات مجاز برنامه.

Handoff چه تفاوتی با Tool دارد؟

در Handoff کنترل اجرا به Agent متخصص منتقل می‌شود، درحالی‌که Function Tool یک قابلیت مشخص را اجرا و نتیجه آن را به گردش کار بازمی‌گرداند.

Agent as Tool چیست؟

روشی برای استفاده از یک Agent متخصص به‌عنوان ابزار است، بدون اینکه Agent اصلی کنترل پاسخ نهایی را به او واگذار کند.

Guardrails چه کاربردی دارند؟

برای بررسی ورودی‌ها، خروجی‌ها یا فراخوانی Toolها استفاده می‌شوند و می‌توانند در شرایط تعریف‌شده اجرای درخواست را مسدود کنند.

آیا Guardrails به‌تنهایی امنیت Agent را تضمین می‌کنند؟

خیر. احراز هویت، کنترل مجوز در Toolها، امنیت شبکه و مدیریت اطلاعات محرمانه همچنان ضروری هستند.

چگونه Agent گفتگوهای قبلی را به خاطر می‌سپارد؟

می‌توانید از Sessions، ارسال دستی تاریخچه یا قابلیت‌های مدیریت وضعیت در سمت OpenAI استفاده کنید.

آیا SQLiteSession برای Production مناسب است؟

برای کاربردهای ساده و تک‌فرآیندی می‌تواند مناسب باشد. برای سامانه‌های چندکاربره پرترافیک، Backend اشتراکی و کنترل دقیق هم‌زمانی معمولاً گزینه بهتری است.

Tracing در Agents SDK چیست؟

قابلیتی برای مشاهده مراحل اجرای Agent، تماس‌های مدل، Toolها، Handoffها و Guardrailها است که به عیب‌یابی و تحلیل عملکرد کمک می‌کند.

آیا می‌توان Tracing را غیرفعال کرد؟

بله. این کار از طریق تنظیمات SDK یا متغیر محیطی OPENAI_AGENTS_DISABLE_TRACING امکان‌پذیر است.

آیا Agent روی VPS پس از Restart دوباره اجرا می‌شود؟

اگر برنامه را با systemd و تنظیمات مناسب راه‌اندازی کنید، سرویس می‌تواند پس از روشن شدن VPS مجدداً اجرا شود.

آیا می‌توان Agent را به وردپرس یا سایت اختصاصی متصل کرد؟

بله. می‌توانید از REST API برنامه استفاده کنید؛ اما باید احراز هویت، HTTPS و کنترل دسترسی کاربران در سمت سرور رعایت شود.

آیا Agent می‌تواند سرور را از طریق SSH مدیریت کند؟

از نظر فنی می‌توان ابزارهای مدیریتی ساخت، اما اجرای مستقیم و نامحدود دستورات Shell توسط مدل توصیه نمی‌شود. بهتر است عملیات مشخص با مجوز محدود و تأیید مناسب تعریف شوند.

برای اجرای چند Agent روی یک VPS چقدر RAM لازم است؟

میزان مصرف به تعداد Workerها، تعداد درخواست‌های هم‌زمان، نوع ابزارهای محلی و پایگاه داده بستگی دارد. در معماری APIمحور معمولاً مصرف برنامه از اجرای محلی یک مدل بزرگ بسیار کمتر است.

آیا VPS قوی‌تر کیفیت پاسخ مدل را افزایش می‌دهد؟

خیر. کیفیت پاسخ بیشتر به مدل، دستورالعمل‌ها، داده‌ها و طراحی ابزارها بستگی دارد. منابع بیشتر VPS عمدتاً به اجرای پایدارتر برنامه و پردازش‌های محلی کمک می‌کنند.

چگونه مصرف API را کنترل کنیم؟

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

جمع‌بندی

ساخت Agent هوش مصنوعی روی VPS با OpenAI Agents SDK به شما امکان می‌دهد یک سرویس هوشمند مستقل برای سایت، نرم‌افزار یا کسب‌وکار خود ایجاد کنید. در این ساختار، VPS برنامه Python، API، ابزارهای محلی و اطلاعات گفتگو را مدیریت می‌کند و OpenAI API پردازش مدل زبانی را انجام می‌دهد.

برای شروع، می‌توانید با Agent و Runner یک دستیار ساده بسازید، سپس با Function Tool قابلیت‌های مشخصی به آن اضافه کنید. با Handoff نیز می‌توانید سوال‌ها و وظایف را به Agentهای متخصص منتقل کنید.

در مرحله بعد، Sessions برای حفظ تاریخچه، Guardrails برای کنترل ورودی و خروجی، و Tracing برای بررسی مسیر اجرا کاربرد دارند. برای انتشار واقعی نیز استقرار با FastAPI، systemd، Nginx و HTTPS، همراه با احراز هویت، محدودیت دسترسی و مانیتورینگ ضروری است.

بهترین مسیر توسعه این است که ابتدا با ابزارهای خواندنی و کم‌خطر شروع کنید، سپس پس از ارزیابی رفتار Agent و کنترل‌های امنیتی، قابلیت‌های مدیریتی حساس‌تر را به سیستم اضافه کنید.