آموزش / پیشرفته: ساختن با API / درس ۱۴ از ۱۵
ساخت یک ایجنت ساده با فراخوانی ابزار (Tool Calling)
با حدود ۶۰ خط پایتون و یک کلید از سرویس ایرانی، ایجنتی بسازید که فایل میخواند و تست اجرا میکند. همان حلقهای که Claude Code و Codex بر پایهاش کار میکنند.
پیشرفته، ۱۰ دقیقه مطالعه
ایجنتهای کدنویسی جادو نیستند. یک حلقهی ساده دارند:
- درخواست و فهرست ابزارها را به مدل میفرستید.
- مدل یا پاسخ نهایی میدهد، یا میگوید «ابزار X را با این ورودی اجرا کن».
- برنامهی شما ابزار را اجرا میکند و نتیجه را به گفتوگو اضافه میکند.
- برمیگردید به گام ۱، تا وقتی مدل پاسخ نهایی بدهد.
پیشنیاز
- پایتون ۳٫۱۰ به بالا و کتابخانهی
openai - کلید یکی از سرویسهای سازگار با OpenAI (راهنمای اتصال)
- مدلی که از ابزار پشتیبانی کند؛ در جدول مدلها فیلتر «پشتیبانی از ابزار» را بزنید
bash
pip install openai
export AI_API_KEY="کلید شما"کد کامل
python
import json, os, pathlib, subprocess
from openai import OpenAI
client = OpenAI(base_url="https://api.avalai.ir/v1", api_key=os.environ["AI_API_KEY"])
MODEL = "MODEL_ID" # شناسهی یک مدل با پشتیبانی ابزار
ROOT = pathlib.Path(".").resolve()
def safe_path(p):
full = (ROOT / p).resolve()
if ROOT not in full.parents and full != ROOT:
raise ValueError("path outside project")
return full
def list_files(path="."):
return "\n".join(str(x.relative_to(ROOT)) for x in safe_path(path).rglob("*.py"))[:8000]
def read_file(path):
return safe_path(path).read_text(encoding="utf-8")[:20000]
def run_tests():
r = subprocess.run(["python", "-m", "pytest", "-q"], cwd=ROOT, capture_output=True, text=True, timeout=180)
return (r.stdout + r.stderr)[-6000:]
TOOLS = {"list_files": list_files, "read_file": read_file, "run_tests": run_tests}
def spec(name, desc, props=None, required=None):
return {"type": "function", "function": {"name": name, "description": desc,
"parameters": {"type": "object", "properties": props or {}, "required": required or []}}}
tools = [
spec("list_files", "List Python files under a folder of the project.", {"path": {"type": "string"}}),
spec("read_file", "Read a text file of the project.", {"path": {"type": "string"}}, ["path"]),
spec("run_tests", "Run the test suite and return the output."),
]
messages = [
{"role": "system", "content": "You are a careful coding assistant. Use the tools to inspect the project before answering. Answer in Persian."},
{"role": "user", "content": "تستها را اجرا کن و اگر شکست خوردند، علت را با خواندن فایلهای مرتبط پیدا کن و توضیح بده."},
]
for step in range(12):
reply = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
msg = reply.choices[0].message
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
print(msg.content)
break
for call in msg.tool_calls:
args = json.loads(call.function.arguments or "{}")
try:
result = TOOLS[call.function.name](**args)
except Exception as e:
result = f"error: {e}"
print(f"→ {call.function.name}({args})")
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})چه چیزی را عمداً نگذاشتیم
این ایجنت نمیتواند فایل بنویسد یا فرمان دلخواه اجرا کند؛ فقط میخواند و تست میگیرد. اگر ابزار نوشتن اضافه میکنید:
- فقط داخل پوشهی پروژه اجازه دهید (تابع
safe_pathهمین کار را میکند). - پیش از اعمال، تغییر را به کاربر نشان دهید و تأیید بگیرید.
- اجرای فرمان دلخواه را فقط در کانتینر جدا مجاز کنید (امنیت).
گامهای بعدی
- محدود کردن هزینه: تعداد گامها (اینجا ۱۲) و طول خروجی ابزارها را محدود نگه دارید.
- ابزارهای استاندارد: بهجای نوشتن ابزار از صفر، از سرورهای MCP استفاده کنید.
- جستوجو در مستندات: ابزاری اضافه کنید که با RAG مستندات پروژه را جستوجو کند.