AI Agent چیست؟ ساخت اولین عامل امن با Python

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

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

چرا AI Agent یک موضوع روبه‌رشد است؟

در بررسی Google Trends ایران در ۹ سپتامبر ۲۰۲۶، سه نامزد Model Context Protocol، Retrieval augmented generation و AI agent مقایسه شدند. دو عبارت اول در ایران داده کافی نداشتند. میانگین AI agent در ۹۰ روز ۹ و در ۱۲ ماه ۴۰ بود؛ اما نمودار ۱۲ماهه از حدود ۳۰ تا ۴۰ در نیمه اول دوره به ۶۸ تا ۱۰۰ در هفته‌های اخیر رسیده است. پس برچسب درست برای این موضوع «روبه‌رشد» است، نه صرفاً تقاضای ثابت.

عبارت‌های مرتبط hermes ai agent، agent router، gemini ai و codex در بخش Rising وضعیت Breakout داشتند. پیشنهادهای واقعی Google نیز نیت‌های ai agent examples، frameworks، skills، course، github، n8n و تفاوت AI agent با agentic AI را نشان دادند. این مقاله به نیت آموزشی و ساخت نمونه پاسخ می‌دهد، اما از معرفی فهرست ابزارهای زودگذر فاصله می‌گیرد.

AI Agent چه تفاوتی با چت‌بات، Workflow و Agentic AI دارد؟

هر اتوماسیونی به Agent نیاز ندارد. اگر مراحل قطعی‌اند، Workflow ساده ارزان‌تر، سریع‌تر و قابل‌آزمایش‌تر است. Agent زمانی ارزش دارد که سیستم باید میان چند ابزار انتخاب کند، از نتیجه میانی یاد بگیرد یا درباره ترتیب گام‌ها تصمیم بگیرد. برای اجرای Workflowهای ثابت روی سرور، راهنمای نصب امن n8n با Docker Compose را ببینید.

معماری کمینه یک عامل هوش مصنوعی

1. Goal: هدف روشن و معیار پایان؛ مثلاً «وضعیت سفارش را فقط بخوان و خلاصه کن».
2. Model: مدلی که ورودی را تحلیل و گام بعد را پیشنهاد می‌کند.
3. Instructions: نقش، محدودیت، سیاست داده و شرایط Escalation.
4. Tools: توابع یا سرویس‌هایی با Schema دقیق و دسترسی حداقلی.
5. State: تاریخچه لازم برای ادامه کار، نه انبار نامحدود داده شخصی.
6. Guardrails: اعتبارسنجی ورودی، خروجی و درخواست Tool.
7. Runner: حلقه‌ای که مدل، Tool و نتیجه را تا توقف هماهنگ می‌کند.
8. Observability: Trace، Metric و Audit برای فهمیدن اینکه چه اتفاقی افتاده است.

Agents SDK رسمی OpenAI این اجزا را با چند Primitive اصلی ارائه می‌کند: Agent، Runner، Tool، Handoff و Guardrail. Tracing داخلی نیز رخدادهای اجرای مدل، Tool Call، Handoff و Guardrail را ثبت می‌کند. ثبت Trace باید با سیاست حریم خصوصی هماهنگ باشد، زیرا ورودی یا خروجی می‌تواند حساس باشد.

راه‌اندازی پروژه Python

برای جداسازی Dependencyها یک محیط مجازی بسازید و بسته رسمی را نصب کنید. کلید API را فقط از Environment Variable یا Secret Manager بخوانید؛ آن را داخل فایل Python، Screenshot، Log یا مخزن Git قرار ندهید.

mkdir safe-order-agentcd safe-order-agentpython -m venv .venvsource .venv/bin/activatepip install openai-agentsexport OPENAI_API_KEY="read-from-your-secret-manager"

در Windows PowerShell فعال‌سازی محیط مجازی با .venv\Scripts\Activate.ps1 انجام می‌شود. مقدار نمونه بالا Secret واقعی نیست. در Production، متغیر را از سامانه مدیریت Secret تزریق و دسترسی آن را به همان Process محدود کنید.

ساخت اولین Agent با یک Tool خواندنی

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

from agents import Agent, Runner, function_tool ORDERS = {    "A-1024": {"status": "shipped", "eta": "2026-09-11"}} @function_tooldef get_order_status(order_id: str) -> dict:    """Read one order status by an ID like A-1024."""    if not order_id.startswith("A-"):        return {"error": "invalid order id"}    return ORDERS.get(order_id, {"error": "not found"}) agent = Agent(    name="Order status assistant",    instructions=(        "Only read order status. Never claim that you changed an order. "        "Ask for a valid order ID and do not reveal unrelated records."    ),    tools=[get_order_status],) result = Runner.run_sync(agent, "Check order A-1024")print(result.final_output)

در سرویس واقعی، Tool باید هویت کاربر را از Context قابل اعتماد بگیرد؛ نه از متنی که خود کاربر نوشته است. سپس Query باید علاوه بر order_id با owner_id محدود شود. توضیح Tool راهنمای مدل است، اما کنترل Authorization باید در کد و دیتابیس اجرا شود.

Tool چگونه به مرز امنیتی تبدیل می‌شود؟

عامل فقط به اندازه Toolهایش قدرت دارد. به‌جای یک تابع عمومی مانند run_sql(query) یا run_shell(command)، Toolهای کوچک و هدفمند بسازید: get_order_status(order_id)، draft_refund_request(order_id) و submit_refund_after_approval(request_id). این جداسازی، Log و تست را ساده و Blast Radius را محدود می‌کند.

چه عملیاتی باید تأیید انسانی داشته باشند؟

• پرداخت، بازپرداخت و انتقال پول
• حذف یا انتشار داده
• ارسال پیام بیرونی به نام کاربر یا شرکت
• تغییر Permission، حساب یا Secret
• اجرای فرمان روی سیستم و تغییر فایل‌های واقعی
• هر تصمیم حقوقی، پزشکی یا مالی پرریسک

تأیید باید جزئیات عملیات نهایی را نشان دهد: چه چیزی، روی کدام شناسه، با چه مبلغ یا گیرنده‌ای تغییر می‌کند. دکمه «تأیید» برای خلاصه مبهم، Human-in-the-loop واقعی نیست.

Guardrail، Authorization و Validation یک چیز نیستند

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

مقابله با Prompt Injection

Prompt Injection زمانی رخ می‌دهد که متن ورودی، صفحه وب یا سند حاوی دستورهایی باشد که می‌خواهند سیاست عامل را دور بزنند. جمله «دستور قبلی را نادیده بگیر» فقط متن است، اما اگر Agent Tool پرقدرت داشته باشد، اثر آن می‌تواند واقعی شود.

• محتوای بیرونی را داده غیرقابل اعتماد فرض کنید، نه دستور سیستم.
• Secret را داخل Prompt یا Context قابل مشاهده مدل نگذارید.
• Toolهای خواندن و نوشتن را جدا و Scope را حداقلی کنید.
• خروجی مدل را مستقیماً به Shell، SQL یا HTML اجرایی وصل نکنید.
• برای مقصد URL، نوع فایل، شناسه و مقدارها Allowlist تعریف کنید.
• عملیات حساس را متوقف و برای تأیید انسانی صف‌بندی کنید.
• سناریوهای حمله را در تست‌های Regression نگه دارید.

Tracing و حریم خصوصی

Tracing به شما نشان می‌دهد عامل چه تصمیمی گرفته، کدام Tool را فراخوانده و Guardrail کجا فعال شده است. مستندات Agents SDK می‌گوید Trace شامل Generation، Tool Call، Handoff و رخدادهای سفارشی است. این داده برای Debug حیاتی است، ولی ممکن است حاوی اطلاعات حساس باشد.

پیش از فعال‌سازی در Production، Redaction، Retention و سطح دسترسی Trace را تعریف کنید. متن کامل کارت بانکی، Token، سند شخصی یا Payload محرمانه نباید صرفاً برای راحتی Debug ثبت شود. Metricهای مفید شامل نرخ موفقیت Task، تعداد Tool Call، هزینه هر اجرا، زمان پاسخ، نرخ Escalation و تعداد Approval ردشده هستند.

آزمون Agent با معیار قابل اندازه‌گیری

1. مجموعه‌ای از درخواست‌های عادی، مبهم، مخرب و خارج از Scope بسازید.
2. نتیجه مطلوب و Tool Call مجاز را برای هر مورد مشخص کنید.
3. بررسی کنید Agent چه زمانی باید سؤال روشن‌کننده بپرسد.
4. اطمینان بگیرید عملیات Write بدون Approval رخ نمی‌دهد.
5. خطای Tool، Timeout و پاسخ ناقص را شبیه‌سازی کنید.
6. هزینه، Latency و نرخ موفقیت را بین نسخه‌ها مقایسه کنید.
7. هر Incident واقعی را به Dataset ارزیابی اضافه کنید.

Specification به Agent می‌گوید موفقیت دقیقاً چیست. اگر معیار پذیرش، موارد خارج از Scope و مسیر خطا هنوز مبهم‌اند، پیش از کدنویسی از روش مقاله توسعه مبتنی بر مشخصات با Spec Kit برای شفاف‌کردن رفتار استفاده کنید.

اشتباه‌های رایج در ساخت AI Agent

شروع با چند عامل

Multi-agent از روز اول، Debug و هزینه را سخت می‌کند. ابتدا یک Agent و چند Tool کوچک بسازید. فقط وقتی مالکیت وظایف و مرز Context روشن شد، Handoff یا Agents-as-tools را اضافه کنید.

دادن Shell یا SQL عمومی

ابزار عمومی انعطاف زیادی دارد، اما کنترل کمی ایجاد می‌کند. Wrapper هدفمند با ورودی Typed، Query پارامتری، Timeout و مجوز محدود امن‌تر است.

نداشتن معیار توقف

Runner باید سقف Turn، Timeout، Budget و شرط پایان داشته باشد. Agent بدون Stop Condition ممکن است میان Toolها بچرخد، هزینه بسازد و نتیجه‌ای تحویل ندهد.

اعتماد به متن روان

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

چک‌لیست Production

• هدف Agent و موارد خارج از Scope نوشته شده‌اند.
• هر Tool کمترین Permission و Schema محدود دارد.
• Authorization در Backend مستقل از مدل اجرا می‌شود.
• عملیات برگشت‌ناپذیر Approval انسانی دارد.
• Secretها خارج از Prompt، Log و Repository هستند.
• Prompt Injection و ورودی مخرب در Eval پوشش داده شده‌اند.
• Timeout، Rate Limit، سقف Turn و Budget تعریف شده‌اند.
• Trace با Redaction و Retention مناسب فعال است.
• Fallback و Escalation برای شکست Tool وجود دارد.
• مالک سرویس، Runbook و Kill Switch مشخص‌اند.

جمع‌بندی

AI Agent یک چت‌بات پرحرف نیست؛ حلقه‌ای تصمیم‌گیر است که به Tool و محیط واقعی متصل می‌شود. ارزش آن در حل مسئله چندمرحله‌ای است و ریسک آن از همان دسترسی‌ها می‌آید. نمونه کوچک با Tool خواندنی، Scope روشن و Trace کامل بسازید؛ سپس Guardrail، Approval و Eval را پیش از اضافه‌کردن اختیار بیشتر توسعه دهید.

برای یادگیری Python، طراحی API و ساخت پروژه‌های AI قابل ارائه، مسیرهای آموزشی خانه برنامه‌نویسان البرز را بررسی کنید.