رابط ابزار چرا ماموران به I/O ساختاری نیاز دارند
tools/call; بخش های وظیفه A2A یک کدگذاری متفاوت از یک حلقه چهار مرحله ای است. این درس حلقه را نام می دهد و حداقل ماشین آلات برای اجرا آن را نشان می دهد.Type: Learn
Languages: Python (stdlib, no LLM)
Prerequisites: Phase 11 (LLM completion APIs)
Time: ~45 minutes
اهداف یادگیری
- توضیح دهید که چرا یک مدرک لیسانس که فقط می تواند متن تولید کند، نمی تواند به تنهایی علیه دنیای واقعی اقدام کند.
- حلقه چهار مرحله ای ابزار تماس (وصف → تصمیم → اجرا → مشاهده) را بکشید و نامگذاری کنید که صاحب هر مرحله است.
- یک توصیف ابزار را به عنوان سه بخش بنویسید: نام، ورودی JSON Schema و یک تابع اجراگر تعیین کننده.
- ابزار های خالص و اثرات جانبی را تشخیص دهید و توضیح دهید که چرا تقسیم برای ایمنی مهم است.
مشکل
یک LLM توزیع احتمال را بر روی توکن بعدی منتشر می کند. این کل سطح خروجی است. اگر از یک مدل چت "حالی در بنگالورو چه هوا است" بپرسید، می تواند یک جمله قابل قبول بنویسد، اما نمی تواند به یک API آب و هوا زنگ بزند. جمله ممکن است به طور تصادفی درست باشد یا سه روز قدیمی باشد.
بسته شدن این شکاف هدف رابط ابزار است. برنامه میزبان زمان اجرا آژانس شما، کلود دسکتاپ، چت جی پی تی، کورسر یا یک اسکریپت سفارشی یک لیست از ابزار قابل تماس به مدل را تبلیغ می کند. مدل، وقتی تصمیم می گیرد که یک عمل مورد نیاز است، یک بار مفید ساختاری را به نام یک ابزار و استدلال های آن می فرستد. میزبان آن بار را تجزیه و تحلیل می کند، ابزار را به طور واقعی اجرا می کند و نتیجه را به شما می دهد. حلقه ادامه داره تا مدل تصميم بگيره ديگه نياز به تماس نيست
اولین نسخه این قرارداد در ژوئن 2023 به عنوان پارامتر "کار" OpenAI ارسال شد.tool_useبلوک هاي کلاود 2.1.functionDeclarationsهر ارائه دهنده در حال حاضر شکل مشابهی را نشان می دهد: یک لیست ابزار JSON-Schema-typed در، یک ابزار JSON-payload call out. پروتکل کنستکت مدل (نومبر 2024) قرارداد را به طور کلی به طوری که یک ثبت ابزار به هر مدل خدمت می کند. A2A (اپریل 2026, v1.0) یک لایه اولیه برای نمایندگی از عامل به عامل را قرار داد.
حلقه چهار مرحله اي که در پشت همه اين ها هست
مفهوم
مرحله اول: شرح
میزبان هر ابزار را با سه میدان اعلام می کند.
- Name.یک شناسه ثابت و قابل خواندن ماشین
get_weatherنه "حاله آب و هوا" - Description.خلاصه ای از یک پاراگراف زبان طبیعی. "در زمانی که کاربر درباره شرایط فعلی یک شهر خاص سوال کند، استفاده کنید. برای اطلاعات تاریخی استفاده نکنید".
- Input schema.یک شیمی JSON Schema (مسود 2020-12) که استدلال ابزار را توصیف می کند.
مدل لیست را دریافت می کند. ارائه دهندگان مدرن این بیانیه ها را با استفاده از یک قالب خاص ارائه دهنده به سیستم سریال می کنند، بنابراین شما به عنوان تماس گیرنده فقط با فرم ساختاری کار می کنید.
مرحله دوم: تصمیم گیری
با توجه به پیام کاربر و ابزار موجود، مدل یکی از سه رفتار را انتخاب می کند.
- Answer directlyدر متن، بدون تماس با ابزار
- Call one or more tools.اجراي تماس هاي ساختاره اي را ارسال کن
parallel_tool_calls: true(به طور پیش فرض در OpenAI و Gemini، انتخاب در Anthropic) مدل می تواند تماس های متعدد را در یک نوبت ارسال کند. - Refuse.در حالت سخت ساختاری، تولیدات می توانند یک نوع تایپ شده را تولید کنند.
refusalبه جای تماس، بلاک
یک باررس تماس ابزار دارای سه میدان ثابت است: یک تماسid، یک ابزارname، و JSONargumentsاسم موجود است تا میزبان بتواند نتیجه بعدی را با تماس خاص مرتبط کند، که وقتی تماس های موازی از ترتیب خارج می شوند مهم است.
مرحله سوم: اجرا
میزبان تماس را دریافت می کند، استدلال ها را در برابر طرح اعلام شده تأیید می کند و اجرای اجرا کننده را اجرا می کند. استدلال های باطل به این معنی است که مدل یک میدان را هالوژین کرده یا از نوع اشتباه استفاده کرده است یک حالت شکست بسیار رایج در مدل های ضعیف. میزبان های تولید یکی از سه کار را در استدلال های باطل انجام می دهند: به سرعت شکست می خورند و خطای را به مدل می کشند، JSON را با یک مرورگر محدود تعمیر می کنند یا مدل را با خطای تأیید شامل در پرامپت دوباره امتحان می کنند.
خود اجرا کننده کد معمولی است. پایتون، تایپ اسکریپت، یک دستور shell، یک سوال پایگاه داده. نتیجه ای تولید می کند که معمولا یک رشته است اما می تواند هر مقدار JSON یا یک بلوک محتوا ساختاری (متن، تصویر یا مرجع منابع در MCP) باشد. نتیجه باید سریال سازی شود.
مرحله چهارم: مشاهده
میزبان نتیجه ابزار را به مکالمه اضافه می کند (به عنوان toolپیام نقش با مطابقتid) و دوباره مدل را فرا می خواند. مدل اکنون ابزار را در زمینه دارد و می تواند پاسخ نهایی را تولید کند یا درخواست تماس های بیشتری را انجام دهد. این تا زمانی که مدل از ارسال تماس ها متوقف شود یا میزبان به محدودیت ایمنی در تعداد تکرار برسد ادامه می یابد.
اعتماد از هم جدا شد
ابزارها دو نوع هستند که برای ایمنی مهم هستند.
- Pure.فقط براي خواندن، ديترمينستي، هيچ عوارض جانبي نداره.
get_weather،search_docs،get_current_time. با اعتماد به نفس تماس بگیرید - Consequential.حالت متحول ميکنه، پول خرج ميکنه، داده هاي کاربران رو لمس ميکنه
send_email،delete_file،execute_tradeباید دروازه اش بسته باشه
در قانون دو برای امنیت عامل میتا 2026 آمده است که یک نوبت می تواند حداکثر دو مورد را ترکیب کند: ورودی غیرقابل اعتماد، داده های حساس، عمل پیامد. رابط ابزار جایی است که شما این قانون را با رد تماس ها، نیاز به تأیید کاربر یا افزایش دامنه اجرا می کنید. برای فصل کامل امنیت و مرحله 14 · 09 برای سیاست های مجوز سطح عامل ببینید.
جایی که حلقه زندگی می کند
| Context | Who describes | Who decides | Who executes |
|---|---|---|---|
| Single-turn function calling (OpenAI/Anthropic/Gemini) | App developer | LLM | App developer |
| MCP | MCP server | LLM via MCP client | MCP server |
| A2A | Agent Card publisher | Calling agent | Called agent |
| Web browser (function-calling agent) | Browser extension / WebMCP | LLM | Browser runtime |
همه جا، چهار مرحله یکسان است. نام ستون ها تغییر می کند؛ ساختار تغییر نمی کند.
چرا فقط از مدل نميخوايم JSON رو ارسال کنيم؟
" از مدل بخواهید که در JSON پاسخ دهد " الگوی پیش از تماس با عملکرد بود. این حدود 5 تا 15 درصد از زمان در مدل های مرز و بسیار بیشتر در مدل های کوچکتر شکست می خورد. حالت های شکست شامل برتری های گمشده، قطب نما عقب، زمینه های توهم و انواع اشتباه است. سپس شما نیاز به یک گذرگاه تعمیر JSON، یک تلاش مجدد یا یک کد کد را محدود می کنید.
تماس با تابع بومی به سه دلیل بهتر است. اول، ارائه دهنده مدل را از انتها به انتها بر اساس شکل تماس دقیق آموزش می دهد، بنابراین نرخ JSON معتبر به 98 تا 99 درصد در حالت سخت می رسد. دوم، بار مفید تماس در فاصله پروتکل خود قرار دارد، نه داخل متن آزاد بنابراین یک تماس ابزار هرگز به پاسخ قابل مشاهده کاربر نفوذ نمی کند. سوم، ارائه دهندگان رعایت طرح را با رمزگذاری محدود (مواد سخت OpenAI، Anthropic) اجرا می کنند.tool_use، دوقلوهاresponseSchema) ، تولید تضمین شده است که تایید شود.
مرحله 13 · 02 سه API ارائه دهنده را کنار هم انجام می دهد. مرحله 13 · 04 به شدت به تولیدات ساختاری می پردازد.
قطع مدار
حلقه زمانی که مدل از ارسال تماس ها متوقف می شود یا میزبان حداکثر تعداد نوبت را می یابد، پایان می یابد. میزبان تولید این مقدار را بین 5 تا 20 نوبت تنظیم می کند. فراتر از آن، تقریباً مطمئناً شما در حلقه ای هستید که مدل نمی تواند از آن خارج شود. کد کلاود به طور پیش فرض به 20 است؛ دستیاران OpenAI به 10 است؛ حالت عامل Cursor به 25.
گزینه ی جایگزین حلقه های بدون مرز هر شش ماه به عنوان "عملی 400 دلار در تماس های API در طول شب" ظاهر می شود. بدون محدودیت ارسال نکنید.
مرحله 14 · 12 شامل بازیابی خطاها و خود بهبود در عمق است؛ مرحله 17 شامل محدودیت های نرخ تولید است.
از اينجا مرحله 13 شروع ميشه
- درس های 02 تا 05 سطح تماس ابزار سطح ارائه دهنده را صاف کنند.
- درس های 06 تا 14 حلقه را به MCP عمومی می کنند.
- درس 15 تا 18 از حلقه در برابر سرورهای دشمنانه، کاربران مخالف و سطوح auth دورانی غیر معتبر دفاع می کند.
- درس های 19 تا 22 الگوی را به همکاری عامل به عامل، مشاهده، مسیر و بسته بندی گسترش می دهند.
- درس 23 يه اکوسیستم کامل با استفاده از هر نوع ابتدایی رو ميخواد
هر درس باقی مانده یک تعدیل از این حلقه چهار مرحله ای است. به عنوان غیر متغیر به خاطر داشته باشید.
ازش استفاده کن
code/main.pyیک تابع "قرر کننده" جعلی مدل را با تطابق الگوی در پیام کاربر شبیه سازی می کند؛ اجرا کننده، تأیید کننده طرح و استفاده از مراحل مشاهده واقعی هستند. آن را اجرا کنید تا کوریوگرافی کامل درخواست / پاسخ را با حالت میانگین چاپی مشاهده کنید، سپس تصمیم دهنده جعلی را با هر ارائه دهنده واقعی در یک درس بعدی جایگزین کنید.
چه چیزی رو باید ببینیم:
- در ثبت ابزار سه زمینه در هر ابزار وجود دارد: نام، توصیف، طرح و یک مرجع اجرا کننده.
- اعتبار دهنده یک زیر مجموعه ی حداقل JSON Schema (تایپ ها، مورد نیاز، enum، min/max) است که تنها به stdlib نوشته شده است. مرحله 13 · 04 یک کامل تر را ارسال می کند.
- تعداد تکرار در 5 عدد محدود می شود. عوامل تولید دقیقاً به این نوع قطع کن نیاز دارند.
-باده
این درس به ما کمک می کندoutputs/skill-tool-interface-reviewer.md. با توجه به یک تعریف طرح ابزار (نام + توصیف + طرح + طرح اجرا کننده) ، مهارت آن را برای تناسب حلقه بررسی می کند: آیا نام ماشین پایدار است، آیا توصیف یک خلاصه استفاده کامل است، آیا طرح از JSON Schema 2020-12 به درستی استفاده می کند و طبقه بندی خالص به مقابل نتیجه صریح است.
تمرینات
- یک ابزار چهارم را به اضافه کنید
code/main.pyتماس گرفتget_stock_price(ticker). توصیف آن را به عنوان "استفاده کنید زمانی که کاربر از قیمت سهام فعلی با تکه استفاده کند. برای قیمت های تاریخی یا خلاصه های بازار استفاده نکنید". استفاده از هرنس و تأیید سوالات راه های تصمیم گیری جعلی با اشاره به تکه به ابزار جدید.
- . سکهای تایید کننده را بشکنه . تماس بگیرید که
argumentsاگر یک فیلدی مورد نیاز از دست رفته باشد، پس از اجرای آن، تایید کنید که میزبان آن را رد می کند. سپس با یک فیلدی نامعلوم اضافی تماس بگیرید. تصمیم بگیرید: آیا میزبان باید رد کند یا نادیده بگیرد؟ انتخاب خود را با یک استدلال ایمنی توجیه کنید.
- هر ابزار در آستین را به عنوان خالص یا نتیجه ای طبقه بندی کنید.
consequential: trueعلامت گذاری به ورودی های ثبت نام که نیاز به آن را، و تغییر حلقه برای چاپ یک " خواهد تایید با کاربر" خط هر زمان یک ابزار نتیجه گیری انتخاب شده است. این شکل دروازه تایید هر میزبان تولید نیاز دارد.
- حلقه چهار مرحله ای را روی کاغذ با جدول ستون ارائه دهنده بالا برای مشتری مورد علاقه خود (Claude Desktop، Cursor، ChatGPT یا یک استیک سفارشی) پر کنید. با نسخه خاص MCP در مرحله 13 · 06 مرجع متقابل کنید.
- راهنمای تماس با عملکرد OpenAI را از بالا تا پایین بخوانید. یک فیلدی را که در درخواست قرار دارد اما در حلقه چهار مرحله ای که در اینجا ارائه شده نیست شناسایی کنید. توضیح دهید که چه چیزی اضافه می شود و چرا مناسب است نه ضروری.
اصطلاحات کلیدی
| Term | What people say | What it actually means |
|---|---|---|
| Tool | "A thing the model can call" | A triple of name + JSON-Schema-typed input + executor function |
| Function calling | "Native tool use" | Provider-level API support for emitting structured tool calls instead of prose |
| Tool call | "The model's request to act" | A JSON payload with id, name, arguments emitted by the model |
| Tool result | "What the tool returned" | The executor's output, wrapped in a tool role message with matching id |
| Parallel tool calls | "Many calls at once" | Multiple call objects in one model turn, independent and orderable by id |
| Strict mode | "Guaranteed JSON" | Constrained decoding that forces the model's output to validate against the declared schema |
| Pure tool | "Read-only tool" | No side effects; safe to re-run |
| Consequential tool | "Action tool" | Mutates external state; requires gate, audit, or user confirmation |
| Four-step loop | "The tool-call cycle" | describe → decide → execute → observe |
| Host | "Agent runtime" | The program that holds the tool registry, calls the model, and runs the executor |
خواندن بیشتر
- OpenAI — Function calling guide مرجع قانونی برای اعلامیه های ابزار و اشکال تماس در سبک OpenAI
- Anthropic — Tool use overview کلود
tool_use-tool_resultقالب بلاک - Google — Gemini function calling
functionDeclarationsو سیمانیک تماس موازی در دوقلوها - Model Context Protocol — Specification 2026-07-28 عمومی سازی فعلی بی دولتی، ارائه دهنده-آگنوستیک رابط ابزار
- JSON Schema — 2020-12 release notes گویش طرح هر ابزار مدرن API صحبت می کند
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.