এজেন্টিক ফর্ম

ডিক্লারেটিভ API অ্যাট্রিবিউটের মাধ্যমে স্ট্যান্ডার্ড HTML <form> এলিমেন্টকে WebMCP টুলে রূপান্তরিত করে। ব্রাউজার ফর্ম ইনপুট থেকে একটি JSON স্কিমা সিন্থেসাইজ করে এবং এজেন্ট ইন্টার‍্যাকশন ম্যানেজ করে।

Angular Signal Forms: @angular/forms/signals থেকে form() দিয়ে তৈরি করা ফর্মে toolname/tooldescription যোগ করবেন না। পরিবর্তে, অ্যাপ প্রদানকারীদের সাথে provideExperimentalWebMcpForms() যোগ করুন এবং experimentalWebMcpTool: { name, description } বিকল্পটি form()-এ পাস করুন। Angular তারপরে ইম্পারেটিভ API-এর মাধ্যমে ফর্মটি রেজিস্টার করে, সিগন্যাল মডেল থেকে স্কিমা তৈরি করে এবং এটিকে যাচাইকরণ এবং জমা দেওয়ার সাথে যুক্ত করে। দুটি পদ্ধতি ব্যবহার করলে একই ফর্ম দুবার রেজিস্টার করা হয়।

ফর্ম অ্যাট্রিবিউট

• toolname: টুলের অনন্য নাম।
• tooldescription: টুলটি কী করে এবং কখন একজন এজেন্টের এটি ব্যবহার করা উচিত। ফর্মের ফিল্ড, বিকল্প বা সীমা তালিকাভুক্ত করবেন না: ব্রাউজার আগে থেকেই ফর্ম কন্ট্রোল থেকে তৈরি করা স্কিমায় সেগুলি অন্তর্ভুক্ত করে।
• toolautosubmit: (ঐচ্ছিক) এটি থাকলে, ব্যবহারকারীর ইন্টার‍্যাকশনের জন্য অপেক্ষা না করেই এজেন্ট ফর্ম জমা দিতে পারবেন।
• toolparamdescription: (ঐচ্ছিক) JSON স্কিমার মধ্যে প্রপার্টির বিবরণ নির্ধারণ করার উপায় প্রদান করে। ভ্যালুর অর্থ কী তা ব্যাখ্যা করতে এটি ব্যবহার করুন (যেমন, স্যাম্পেল ভ্যালু সহ), কন্ট্রোলের বিকল্প বা সীমা পুনরাবৃত্তি করতে নয়।
  • রেজোলিউশন অর্ডার: ব্রাউজার toolparamdescription ব্যবহার করে, যদি তা উপলভ্য থাকে। এটি না থাকলে, এটি সংশ্লিষ্ট <label>-এর textContent ব্যবহার করে (লেবেল করা যায় এমন ডিসেন্ডেন্ট বাদ দিয়ে)। কোনও লেবেল না থাকলে, এটি aria-description-এ ফিরে যায়।
  • গ্রুপিং (ফিল্ডসেট): সম্পর্কিত এলিমেন্টের (যেমন <input type="radio"> বোতাম) কোনও গ্রুপের সাথে বিবরণ অ্যাটাচ করতে, সবচেয়ে কাছের পেরেন্ট <fieldset> এলিমেন্টে toolparamdescription রাখুন যাতে এটি সম্পূর্ণ প্যারামিটার গ্রুপে প্রযোজ্য হয়।

উদাহরণ

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

জাভাস্ক্রিপ্টে জমা দেওয়া ম্যানেজ করা

কোনও এজেন্ট ফর্ম জমা দিলে, SubmitEvent-এ agentInvoked (বুলিয়ান) ও respondWith(promise) অন্তর্ভুক্ত থাকে।

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

লাইফসাইকেল ইভেন্ট

এজেন্ট কোনও টুলের সাথে ইন্টার‍্যাক্ট করা শুরু বা বন্ধ করলে document.modelContext ইভেন্ট এমিট করে: টুল এক্সিকিউশন শুরু হলে toolactivated ফায়ার করে এবং এটি বাতিল করা হলে toolcancel ফায়ার করে।

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

ভিজ্যুয়াল ফিডব্যাক (CSS)

এজেন্ট ইন্টার‍্যাক্ট করার সময় ফর্ম হাইলাইট করতে সিউডো-ক্লাস ব্যবহার করুন:

• :tool-form-active: এজেন্ট সক্রিয়ভাবে ব্যবহার করে এমন <form> এলিমেন্টে প্রয়োগ করা হয়েছে।
• :tool-submit-active: ব্যবহারকারীর পর্যালোচনার জন্য ব্রাউজার পজ করা হলে জমা দেওয়ার বোতামে প্রয়োগ করা হয় (যদি toolautosubmit বাদ দেওয়া হয়)।

form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

ফর্মের উপযোগিতা (কখন এড়িয়ে যেতে হবে)

ডিক্লারেটিভ API সেল্ফ-কন্টেনড, স্ট্যান্ডার্ড ফর্মের জন্য সবচেয়ে ভালো। এইসব পরিস্থিতিতে এটি বেছে নেওয়া ঠিক নয়:

• অত্যন্ত নির্ভরশীল ফিল্ড: এমন ফর্ম যেখানে ইনপুটগুলি অন্যান্য ইনপুটের উপর ভিত্তি করে বিকল্প বা দৃশ্যমানতা পরিবর্তন করে। সিন্থেসাইজ করা স্কিমা এইসব নির্ভরতা ভালোভাবে প্রকাশ করতে পারে না।
• কাস্টম UI কম্পোনেন্ট: নন-স্ট্যান্ডার্ড ইনপুটের (যেমন, ক্যানভাস, রিচ টেক্সট এডিটর) উপর নির্ভর করে তৈরি ফর্ম যা ভ্যালু অটো-সিরিয়ালাইজ করে না।
• মাল্টি-স্টেপ উইজার্ড: জটিল ওয়ার্কফ্লো যার জন্য একাধিক ফর্ম জমা দিতে হয়। ইম্পারেটিভ API বা স্ট্যান্ডার্ড DOM ইন্টার‍্যাকশন এখানে আরও উপযুক্ত।

toolautosubmit কখন ব্যবহার করতে হবে

• শুধু-পড়ার-জন্য অপারেশন ও কোয়েরি: সার্চ, ফিল্টার, বিবরণ ফেচ করা বা স্ট্যাটাস চেক করা (যেমন, কোনও গাড়ির মডেল সার্চ করা, ডিরেক্টরি সার্চ করা, স্টক উপলভ্য আছে কিনা তা চেক করা)।
• কম-ঝুঁকিপূর্ণ, রিভার্সিবল অ্যাকশন: ফর্মের অ্যাকশন যা ব্যবহারকারী সহজেই ম্যানুয়ালি আগের অবস্থায় ফিরিয়ে আনতে বা রিফাইন করতে পারেন (যেমন, কার্টে আইটেম যোগ করা, কুপন কোড প্রয়োগ করা, ড্রাফ্ট সেভ করা বা সাময়িক লেআউট বিকল্প সেট করা)।

toolautosubmit কখন বাদ দিতে হবে

• ধ্বংসাত্মক বা অপরিবর্তনীয় অ্যাকশন: রেকর্ড মুছে ফেলা, সিস্টেম কনফিগারেশন রিসেট করা বা ডেটাবেস মুছে ফেলা।
• ফাইন্যান্সিয়াল ও ট্রানজ্যাকশন সংক্রান্ত অ্যাকশন: চেক-আউট ফর্ম জমা দেওয়া, ফান্ড ট্রান্সফার করা, সাবস্ক্রিপশন পেমেন্ট অনুমোদন করা অথবা চূড়ান্ত অর্ডার প্লেস করা।
• ব্যবহারকারীর সাথে হাই-ইমপ্যাক্ট কমিউনিকেশন: চাকরির জন্য চূড়ান্ত আবেদন জমা দেওয়া, অন্যান্য আসল ব্যবহারকারীকে ইমেল/মেসেজ পাঠানো অথবা সর্বজনীন কন্টেন্ট প্রকাশ করা।
• সংবেদনশীল অ্যাকাউন্ট সেটিংস: পাসওয়ার্ড পরিবর্তন করা, ব্যবহারকারীর ভূমিকা/অনুমতি পরিবর্তন করা অথবা বিলিং/প্রোফাইল সংক্রান্ত তথ্য আপডেট করা।

ফলব্যাক স্ট্র্যাটেজি

WebMCP ডিক্লারেটিভ API সব ব্রাউজারে ব্যবহার করা নিরাপদ। যেসব ব্রাউজারে WebMCP কাজ করে না, সেগুলি tool* অ্যাট্রিবিউট উপেক্ষা করবে এবং <form> সাধারণ HTML ফর্ম হিসেবে কাজ করা চালিয়ে যাবে। কোনও ফিচার শনাক্তকরণের প্রয়োজন নেই।