کدنماAI-Coding.irتازه‌های هوش مصنوعی و کدنویسی
دلار (تتر) ۲۷۰٬۳۵۴ تومانAMD ۵۲۴٫۱۳ ▲ +۴٫۱٪AVGO ۳۵۵٫۳۴ ▲ +۴٫۰٪AMZN ۲۶۶٫۹۶ ▲ +۳٫۵٪NVDA ۱۵۰٫۹۶ ▼ −۲٫۹٪BABA ۸۵٫۱۱ ▼ −۱٫۸٪SPCX ۱۴۳٫۹۹ ▲ +۱٫۶٪پرکاربردترین مدل برنامه‌نویسی DeepSeek V4.1 Flash 1017

آموزش / پیشرفته: ساختن با API / درس ۱۴ از ۱۵

ساخت یک ایجنت ساده با فراخوانی ابزار (Tool Calling)

با حدود ۶۰ خط پایتون و یک کلید از سرویس ایرانی، ایجنتی بسازید که فایل می‌خواند و تست اجرا می‌کند. همان حلقه‌ای که Claude Code و Codex بر پایه‌اش کار می‌کنند.

پیشرفته، ۱۰ دقیقه مطالعه

در این آموزش
  1. پیش‌نیاز
  2. کد کامل
  3. چه چیزی را عمداً نگذاشتیم
  4. گام‌های بعدی

ایجنت‌های کدنویسی جادو نیستند. یک حلقه‌ی ساده دارند:

  1. درخواست و فهرست ابزارها را به مدل می‌فرستید.
  2. مدل یا پاسخ نهایی می‌دهد، یا می‌گوید «ابزار X را با این ورودی اجرا کن».
  3. برنامه‌ی شما ابزار را اجرا می‌کند و نتیجه را به گفت‌وگو اضافه می‌کند.
  4. برمی‌گردید به گام ۱، تا وقتی مدل پاسخ نهایی بدهد.

پیش‌نیاز

  • پایتون ۳٫۱۰ به بالا و کتابخانه‌ی 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 مستندات پروژه را جست‌وجو کند.