ایجنٹ کا ٹول کانٹیکسٹ ایڈجسٹ کریں

یہ گائیڈ دو درجوں والی ٹول سطح کے گرد عملی کام کا احاطہ کرتی ہے: یہ دیکھنا کہ ایک رن اصل میں کیا بھیجتا ہے، اُسے بدلنا، اور ایسے ایجنٹ کی تشخیص کرنا جس نے غلط ٹول اُٹھایا۔ یہ اِس طرح کیوں کام کرتا ہے، یہ جاننے کے لیے ٹول کانٹیکسٹ اور پرامپٹ کیشنگ پڑھیں۔

دیکھیں کہ ایک رن اصل میں کیا بھیجتا ہے

کوئی گفتگو کھولیں اور گفتگو کے ہیڈر میں کانٹیکسٹ استعمال کے اشارے پر ٹیپ کریں۔ یہ بالکل وہی سطح دوبارہ بناتا ہے جو اگلا ڈسپیچ بھیجے گا، بغیر کچھ چلائے۔ مزید دیکھیں (یا /context کمانڈ) مکمل کانٹیکسٹ ایکسپلورر کھولتا ہے، جہاں آپ ہر ٹول کا جائزہ لے سکتے ہیں۔

یہاں دو حصے اہم ہیں:

ٹول تعریفیں اور MCP اور ڈائنامک ٹولز — ریذیڈنٹ مجموعہ، ہر ٹول کی اصل ٹوکن لاگت کے ساتھ۔
طلب پر لوڈ ٹولز — طلب پر لوڈ انڈیکس۔ ہر اندراج پر صرف اُس کے نام کا معاوضہ پڑتا ہے، کیونکہ درخواست میں نام ہی جاتا ہے؛ کسی اندراج کو کھولنے پر پھر بھی مکمل تفصیل اور اسکیما دکھائی دیتی ہے، تاکہ آپ دیکھ سکیں کہ اگر رن اُسے اندر کھینچ لے تو کیا لاگت پڑے گی۔

اگر طلب پر لوڈ حصہ خالی ہو، تو اِس سرور کے لیے طلب پر لوڈ بند ہے۔ cc_server CLI پر --tool-deferral دیکھیں۔

یہ بدلیں کہ کون سے ٹولز شروع میں لوڈ ہوں

ریذیڈنٹ مجموعہ پالیسی ہے، کنفیگریشن نہیں — یہ ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) میں رہتا ہے اور ہر رن پر لاگو ہوتا ہے:

residentBuiltins — فائل اور شیل کے الفاظ کا مجموعہ۔
residentDiscovery — search_tools اور list_my_tools۔ اِنہیں ہٹائیں نہیں؛ ایجنٹ اِنہی کے ذریعے باقی سب تک پہنچتا ہے۔
residentMcpTools — وہ مٹھی بھر Control Center ٹولز جو ہر درخواست پر اپنے اسکیما کے قابل ہیں۔
فی موڈ ایک بلاک، اُن ٹولز کے لیے جو کوئی دیا گیا موڈ تقریباً ہر باری میں استعمال کرتا ہے۔

اِسے ترمیم کرتے وقت دو اصول:

ٹول صرف اُسی صورت میں شامل کریں جب زیادہ تر رنز اُسے استعمال کرتے ہوں۔ ہر نام کی قیمت اُس کے اسکیما کی صورت میں ہر رن کی ہر درخواست پر ہمیشہ پڑتی رہتی ہے۔ ایسا ٹول جو استعمال ہونے پر اہم ہو مگر مجموعی طور پر کم ہو، طلب پر لوڈ والے حصے میں رکھا جانا چاہیے — ایجنٹ اُسے پھر بھی ڈھونڈ لے گا۔

ٹول کا اصل نام استعمال کریں۔ ایسا ریذیڈنٹ نام جو کسی ٹول سے نہ ملے، بےاثر ہوتا ہے: نہ کوئی خرابی، نہ کوئی انتباہ، ٹول محض طلب پر لوڈ ہو جاتا ہے۔ test/tooling/resident_tool_names_test.dart اِسے پکڑ لیتا ہے اور یہ بھی یقینی بناتا ہے کہ ہر موڈ 40 ریذیڈنٹ ٹولز سے کم رہے، اور بات بھی یہی ہے — اُس حد سے آگے ٹول کا انتخاب قابلِ پیمائش حد تک بگڑ جاتا ہے۔

کسی موڈ کے لازمی اور پن شدہ فعل خودکار طور پر شامل ہو جاتے ہیں، اس لیے آپ کو موڈ کا اپنا آؤٹ پٹ فعل کبھی درج کرنے کی ضرورت نہیں۔

غلط ٹول کے انتخاب کی تشخیص کریں

جب کسی ایجنٹ نے غلط ٹول استعمال کیا یا دعویٰ کیا کہ وہ کوئی کام نہیں کر سکتا، تو معلوم کریں کہ تین چیزوں میں سے کون سی ہوئی۔

1. کیا اُس نے دیکھا؟

ہر رن ریکارڈ کرتا ہے کہ اُس نے کون سے طلب پر لوڈ ٹولز لوڈ کیے اور اُسے کس چیز نے متحرک کیا — نام لے کر براہِ راست کال، یا کوئی search_tools استفسار۔ رن کا ایونٹ اسٹریم کھولیں (ترتیبات → ورک اسپیس → ایجنٹس → ایجنٹ → لاگز → دیکھیں) اور [harness] loaded N deferred tool(s) ڈھونڈیں۔

کچھ لاگ نہیں ہوا، اور ایجنٹ نے کہا کہ قابلیت موجود نہیں — اُس نے کبھی دیکھا ہی نہیں۔ یہ پرامپٹ کا مسئلہ ہے، ریٹریول کا نہیں: طلب پر لوڈ انڈیکس اُس کے سسٹم پرامپٹ میں موجود ہوتا ہے، اِس ہدایت کے ساتھ کہ جب تک کوئی تلاش خالی واپس نہ آئے، کسی قابلیت کو غائب قرار نہ دے۔
تلاش لاگ ہوئی، مگر کچھ لوڈ نہیں ہوا — یہ واقعی ریٹریول مس ہے۔ قدم 2 پر جائیں۔
ٹولز لوڈ ہوئے، غلط استعمال ہوا — جن ٹولز کو اُس نے پایا وہ بہت زیادہ ہم شکل ہیں۔ قدم 3 پر جائیں۔

2. ریٹریول مس ٹھیک کریں

search_tools ناموں، تفصیلات اور آرگیومنٹ ناموں پر مماثلت کرتا ہے۔ مس کا مطلب تقریباً ہمیشہ یہ ہوتا ہے کہ تفصیل میں وہ الفاظ نہیں جو ایجنٹ نے استعمال کیے۔

وہ شامل کریں۔ تفصیلات ہی ریٹریول انڈیکس ہیں، اس لیے اُنہیں چھوٹا کرنے کے بجائے لمبا کریں — وہی الفاظ لکھیں جو ایک آپریٹر واقعی ٹائپ کرے گا (“assign”، “hand off”، “give to”)، نہ کہ صرف اندرونی اسم۔ ٹوکنز بچانے کے لیے تفصیل کاٹنا آپ کو تلاش کی کامیابی اور انتخاب کی درستگی، دونوں سے محروم کرتا ہے، اور اسکیما کے مقابلے میں تقریباً کچھ بچاتا بھی نہیں۔

اگر صحیح ٹول موجود ہو مگر درجہ بندی میں نیچے ہو، تو limit آرگیومنٹ اسی لیے ہے؛ ٹول کی اپنی تفصیل ایجنٹ کو بتاتی ہے کہ ایسی تلاش کو وسیع کرے جو قریب لگے مگر چوک جائے۔

3. ہم شکل ٹولز ٹھیک کریں

اگر دو ٹولز کی تفصیلات ایسے شخص کے لیے ایک جیسی پڑھی جائیں جو پہلے سے فرق نہ جانتا ہو، تو ماڈل اندازہ لگا رہا ہے۔ اُنہیں ایک ایسے ٹول میں ضم کریں جس میں فرق کرنے والا ایک آرگیومنٹ ہو۔

ticket_relation اور ticket_pr_link اسی نمونے کی پیروی کرتے ہیں: ہر ایک لنک کرنا اور لنک ہٹانا ایک فرق کرنے والے آرگیومنٹ کے ذریعے سنبھالتا ہے۔ ایک کال کے اندر، درخواست کے مکمل کانٹیکسٹ کے ساتھ کیا گیا انتخاب، دو ہم شکل تفصیلات کے درمیان کیے گئے انتخاب سے زیادہ قابلِ اعتماد ہوتا ہے۔

ٹولز الگ رکھیں جب اُنہیں مختلف منظوری گیٹنگ، مختلف آڈٹنگ یا مختلف رینڈرنگ درکار ہو — یہ ایسی وجوہات ہیں جن کی بنا پر ضم کرنا آپ کو واقعی کچھ مہنگا پڑے گا۔

جانچیں کہ پرامپٹ کیش کام کر رہا ہے

کیش ہٹ ریٹ آبزرویبلٹی → بصیرتیں میں کیش ریٹ کے طور پر نظر آتا ہے۔ ایک صحت مند، طویل چلنے والی گفتگو اُونچی سطح پر رہتی ہے؛ اگر یہ مسلسل کم رہے، تو کوئی چیز ہر باری میں پریفکس دوبارہ لکھ رہی ہے۔

عام وجوہات، امکان کی ترتیب سے:

پرامپٹ کے شروع میں کوئی بھی غیر متعین چیز۔ ایک ٹائم اسٹیمپ، درخواست کی ایک آئی ڈی، یا کوئی سیٹ جس پر مختلف ترتیب سے تکرار ہو، یہ کر ڈالے گی۔
گفتگو کے بیچ ماڈل یا ریزننگ کے زور کی تبدیلی۔ دونوں پریفکس بدل دیتے ہیں۔ سب ایجنٹس کے ساتھ یہاں غلطی خاصی آسان ہے: پیسے بچانے کے لیے بچوں کو کم ریزننگ زور پر چلانا، کھوئی ہوئی کیش شیئرنگ کی صورت میں اُس سے زیادہ مہنگا پڑ سکتا ہے جتنے وہ بچاتا ہے۔
بار بار کمپیکشن۔ کمپیکشن اپنی بناوٹ ہی میں تاریخ دوبارہ لکھتا ہے، اس لیے اُس کی لاگت حقیقی ہے؛ حل یہ ہے کہ کم اور گہرا کمپیکٹ کریں، بار بار اور ہلکا نہیں۔

--tool-deferral=off سے طلب پر لوڈ بند کرنا ایک جائز A/B ہے، اس بات کو الگ کرنے کے لیے کہ کسی رویے کی تبدیلی دو درجوں والی سطح سے آئی یا نہیں۔ یہ طلب پر لوڈ سے پہلے کی درخواست بالکل ویسی ہی دوبارہ بناتا ہے، اس لیے اگر اُسے بند رکھنے پر بھی رویہ برقرار رہے، تو سطح اُس کی وجہ نہیں۔