ساخت نخستین عامل هوش مصنوعی با پایتون و OpenAI Agents SDK
ساخت یک عامل هوش مصنوعی با پایتون اکنون بسیار ساده‌تر از گذشته است. با استفاده از OpenAI Agents SDK می‌توانید عامل‌های هوش مصنوعی بسازید، آن‌ها را به ابزارهای مختلف متصل کنید، وضعیت گفت‌وگو را حفظ کنید و جریان‌های کاری چندمرحله‌ای را اجرا کنید؛ بدون آنکه لازم باشد حلقه فراخوانی ابزارها را از ابتدا پیاده‌سازی کنید.
در این آموزش، یک عامل پژوهشی کاربردی می‌سازیم که می‌تواند در وب جست‌وجو کند، یک تابع اختصاصی پایتون را فراخوانی کند، پیام‌های قبلی را به خاطر بسپارد و تشخیص دهد چه زمانی باید از هر قابلیت استفاده کند.
عامل هوش مصنوعی چیست؟
یک برنامه معمولی مبتنی بر مدل زبانی بزرگ (LLM) اغلب از روند ساده‌ای پیروی می‌کند:
پرامپت — مدل — پاسخ
مدل یک پرامپت دریافت می‌کند، پاسخ را تولید می‌کند و کارش به پایان می‌رسد.
اما عامل هوش مصنوعی علاوه بر این، ابزارها و یک حلقه اجرایی دارد:
کاربر — عامل — ابزار در صورت نیاز — عامل — پاسخ نهایی
عامل به‌جای آنکه صرفاً متن تولید کند، می‌تواند تصمیم بگیرد که ابتدا باید اقدامی انجام دهد؛ برای مثال، در وب جست‌وجو کند، تابعی در پایتون را اجرا کند یا اطلاعاتی را از حافظه بازیابی کند.
در OpenAI Agents SDK، مؤلفه Runner این فرایند را به‌صورت خودکار مدیریت می‌کند. این مؤلفه درخواست را به مدل می‌فرستد، ابزارهای درخواستی را اجرا می‌کند، نتایج را به عامل برمی‌گرداند و این روند را تا زمانی ادامه می‌دهد که عامل پاسخ نهایی را تولید کند.
توانایی استدلال، استفاده از ابزارها و ادامه کار در چند مرحله همان چیزی است که یک عامل را از یک برنامه ساده مبتنی بر مدل زبانی بزرگ متمایز می‌کند.
راه‌اندازی پروژه
پیش از ساخت عامل، بهتر است یک محیط پایتون تمیز ایجاد کنیم و ابزارهای موردنیاز را نصب کنیم.
با استفاده از uv یک پروژه پایتون بسازید:
mkdir first-ai-agent
cd first-ai-agent
uv init
uv add openai-agentsروش دیگر، نصب بسته با pip است:
pip install openai-agentsکلید API مربوط به OpenAI را تنظیم کنید:
export OPENAI_API_KEY="your-api-key"در ویندوز، دستور export در Git Bash کار می‌کند. در Command Prompt یا PowerShell می‌توانید از دستور زیر استفاده کنید:
setx OPENAI_API_KEY "your-api-key"اکنون می‌توانیم با چند خط کد پایتون عاملی بسازیم که تشخیص دهد چه زمانی برای پاسخ‌گویی به اطلاعات تازه وب نیاز دارد.
فایلی به نام main.py ایجاد کنید:
from agents import Agent, Runner, WebSearchTool
agent = Agent(
name="Research Assistant",
instructions=(
"You are a concise research assistant. "
"Use web search when current information is required."
),
tools=[WebSearchTool()],
)
result = Runner.run_sync(
agent,
"What are the latest developments in Python?"
)
print(result.final_output)اجرای برنامه:
uv run main.pyخروجی:
As of **September 14, 2026**, the major Python developments are:
- **Python 3.14 is the latest stable feature series**; the newest maintenance
release is **3.14.7**. It adds officially supported free-threaded builds,
deferred annotation evaluation, template string literals (`t""`), ...
- **Python 3.15 is nearing release**: the final release is scheduled for
**October 1, 2026**. ...
For new projects, **Python 3.14.7** is currently the safest default.WebSearchTool() ابزاری میزبانی‌شده از سوی OpenAI است. بنابراین، مدل می‌تواند خودش تشخیص دهد که چه زمانی به اطلاعات روز نیاز دارد و لازم نیست شما به‌صورت دستی یک رابط برنامه‌نویسی جست‌وجو را فراخوانی کنید.
برای مثال، اجرای آزمایشی ما به‌درستی نسخه 3.14.7 پایتون را به‌عنوان نسخه پایدار فعلی شناسایی کرد.
افزودن ابزار اختصاصی پایتون
جست‌وجوی وب کاربردی است، اما وقتی عامل‌ها بتوانند با کد پایتون خودتان نیز تعامل داشته باشند، قابلیت‌های آن‌ها بسیار بیشتر می‌شود.
یک ابزار محاسباتی اضافه کنید:
from agents.decorators import tool
@tool
def calculate_total(
price: float,
quantity: int
) -> float:
"""Calculate the total cost of an order."""
return price * quantityسپس این ابزار را در اختیار عامل قرار دهید:
agent = Agent(
name="Assistant",
instructions="Help with research and calculations.",
tools=[
WebSearchTool(),
calculate_total,
],
)آزمایش ابزار:
result = Runner.run_sync(
agent,
"I need 14 GPUs costing $2.49 each per hour. "
"What will they cost per hour?"
)
print(result.final_output)خروجی:
14 GPUs x $2.49/hour = **$34.86 per hour**.این کیت توسعه به‌صورت خودکار از نام تابع، آرگومان‌ها، اعلان‌های نوع داده و توضیحات تابع استفاده می‌کند تا ساختاری از ابزار ایجاد کند که مدل بتواند آن را درک کند. نیازی نیست طرح‌واره‌های JSON را دستی تعریف کنید یا حلقه فراخوانی ابزارها را خودتان بنویسید.
نکته: توضیحات توابع را روشن و دقیق بنویسید؛ زیرا به مدل کمک می‌کنند بفهمد هر ابزار چه کاری انجام می‌دهد و چه زمانی باید از آن استفاده کند.
افزودن حافظه گفت‌وگو
عامل کاربردی نباید با رسیدن هر پیام جدید، تمام اطلاعات قبلی را فراموش کند. بنابراین، در ادامه قابلیت حافظه گفت‌وگو را به آن اضافه می‌کنیم.
برای آنکه عامل بتواند گفت‌وگویی پیوسته داشته باشد، یک نشست ایجاد کنید:
from agents import SQLiteSession
session = SQLiteSession(
"user_1",
"conversations.db"
)سپس این نشست را در هر بار اجرا به عامل بدهید:
while True:
message = input("You: ")
if message.lower() in {"exit", "quit"}:
break
result = Runner.run_sync(
agent,
message,
session=session,
)
print("Agent:", result.final_output)اکنون این قابلیت را امتحان کنید:
درخواست دوم به‌طور خودکار سابقه گفت‌وگوی قبلی را دریافت می‌کند؛ بنابراین، عامل متوجه می‌شود که منظور از عبارت «جدیدترین نسخه» چیست.
از آنجا که در این مثال از پایگاه داده SQLite مبتنی بر فایل استفاده کرده‌ایم، سابقه گفت‌وگو پس از راه‌اندازی مجدد برنامه نیز حفظ می‌شود.
برای برنامه‌های بزرگ‌تر، این کیت توسعه از سامانه‌های ذخیره‌سازی نشست دیگری مانند Redis، SQLAlchemy و MongoDB نیز پشتیبانی می‌کند.
عامل کامل چگونه کار می‌کند؟
در این مرحله، تمام اجزا در کنار هم قرار می‌گیرند:
عامل تصمیم می‌گیرد چه اقدامی انجام دهد، مؤلفه Runner حلقه اجرای عامل و ابزارهای درخواستی را مدیریت می‌کند و نشست، سابقه گفت‌وگو را میان درخواست‌ها حفظ می‌کند.
در ادامه، کد کامل فایل main.py آمده است:
import os
import sys
from agents import Agent, Runner, SQLiteSession, WebSearchTool
from agents.decorators import tool
@tool
def calculate_total(
price: float,
quantity: int
) -> float:
"""Calculate the total cost of an order."""
return price * quantity
def main() -> None:
if not os.environ.get("OPENAI_API_KEY"):
sys.exit(
"Error: set the OPENAI_API_KEY environment variable first."
)
agent = Agent(
name="Assistant",
instructions="""
Help the user with research and calculations.
Use the available tools when necessary.
""",
tools=[
WebSearchTool(),
calculate_total,
],
)
session = SQLiteSession(
"user_1",
"conversations.db"
)
try:
while True:
try:
message = input("You: ")
except (EOFError, KeyboardInterrupt):
print()
break
command = message.strip().lower()
if command in {"exit", "quit"}:
break
if not command:
continue
try:
result = Runner.run_sync(
agent,
message,
session=session,
)
except Exception as exc:
print(
f"Agent error "
f"({type(exc).__name__}): {exc}"
)
continue
print("Agent:", result.final_output)
finally:
session.close()
if __name__ == "__main__":
main()این کد یک عامل گفت‌وگومحور کوچک اما کامل در اختیار ما قرار می‌دهد که از جست‌وجوی وب، ابزار اختصاصی پایتون، حافظه پایدار، مدیریت خطاهای پایه و رابط گفت‌وگوی پیوسته برخوردار است.
قابلیت ردیابی اجرا نیز به‌صورت پیش‌فرض در Agents SDK فعال است. این ویژگی زمانی که جریان‌های کاری پیچیده‌تر می‌شوند، کاربرد ویژه‌ای دارد. ردپاهای اجرا به شما امکان می‌دهند فراخوانی‌های مدل، استفاده از ابزارها، انتقال کنترل و سایر مراحل طی‌شده در هر اجرای عامل را بررسی کنید.
می‌توانید این ردپاها را در داشبورد OpenAI بررسی کنید تا متوجه شوید عامل چگونه به پاسخ خود رسیده، کدام ابزارها را انتخاب کرده و مشکلات در کجا رخ داده‌اند. این قابلیت به‌ویژه برای اشکال‌زدایی رفتار فراخوانی ابزارها و بهبود دستورالعمل‌های عامل مفید است.
جمع‌بندی
ساخت نخستین عامل هوش مصنوعی بیش از آنکه به معنای ایجاد یک سامانه خودمختار پیچیده باشد، به این معناست که به مدل امکان دهید اقدام‌های مفیدی انجام دهد.
در این راهنما، کار را با یک عامل ساده آغاز کردیم، جست‌وجوی وب را به آن افزودیم، یک ابزار اختصاصی پایتون را متصل کردیم، حافظه پایدار گفت‌وگو را به کار گرفتیم و همه اجزا را در قالب برنامه‌ای کامل با قابلیت ردیابی اجرا و مدیریت خطا کنار هم قرار دادیم.
همین زیرساخت برای ساخت جریان‌های کاری توانمندتر از آنچه انتظار می‌رود کافی است. از این مرحله به بعد، می‌توانید هم‌زمان با رشد برنامه، به‌تدریج رابط‌های برنامه‌نویسی کاربردی (APIها)، سرورهای MCP، سازوکارهای حفاظتی، انتقال کنترل، ابزارهای تخصصی‌تر و عامل‌های بیشتر را اضافه کنید.
الگوی کلی همچنان یکسان است: ابزارهای مناسب را در اختیار عامل قرار دهید، اجازه دهید خودش زمان استفاده از آن‌ها را تشخیص دهد و اجرای مراحل را به کیت توسعه Agents SDK بسپارید.
از یک پروژه کوچک شروع کنید، یک جریان کاری واقعاً کاربردی بسازید و تنها زمانی پیچیدگی را افزایش دهید که به آن نیاز داشته باشید.
عبید علی اعوان (@1abidaliawan) متخصص حرفه‌ای علوم داده دارای گواهی‌نامه است و به ساخت مدل‌های یادگیری ماشین علاقه دارد. او در حال حاضر بر تولید محتوا و نگارش وبلاگ‌های فنی درباره فناوری‌های یادگیری ماشین و علم داده تمرکز کرده است. اعوان مدرک کارشناسی ارشد مدیریت فناوری و مدرک کارشناسی مهندسی مخابرات دارد. چشم‌انداز او ساخت محصولی مبتنی بر شبکه عصبی گرافی برای دانش‌آموزانی است که با مشکلات سلامت روان دست‌وپنجه نرم می‌کنند.