.NET developer-দের জন্য AI engineering (পর্ব 7): workflow, agent ও মানুষের সই
review report-এর জন্য state machine, four-eyes approval, stale data-র পাহারা আর সীমা-বাঁধা agent loop: 14টা test-করা scenario সহ।

ধরুন, আপনার AI সিস্টেম চমৎকার একটি পোর্টফোলিও রিপোর্ট তৈরি করে ফেলেছে। পর্ব 6-এর শেষে আমরা দেখেছি কীভাবে আলফা টেকের হোল্ডিং রিপোর্টের প্রতিটি দাবির নিচে সুনির্দিষ্ট প্রামাণিক সূত্রের রেফারেন্স (পাদটীকা) যুক্ত করা হয় এবং C# কোড প্রতিটি সংখ্যা ও উদ্ধৃতি নিখুঁতভাবে মিলিয়ে নেয়।
কিন্তু একটি পেশাদার আর্থিক প্রতিষ্ঠানে এই স্বয়ংক্রিয় খসড়া তৈরি হওয়াই শেষ কথা নয়। প্রোডাকশনে ডেপ্লয় করার মুহূর্তে তিনটি অত্যন্ত গুরুতর বাস্তব প্রশ্ন সামনে এসে দাঁড়ায়:
- চূড়ান্ত অনুমোদন বা সই করবে কে? রিপোর্ট প্রস্তুতকারী নিজেই কি নিজেকে অনুমোদন দিতে পারেন, নাকি চার-চোখের নীতি (Four-Eyes Principle) অনুযায়ী সম্পূর্ণ স্বাধীন দ্বিতীয় একজন মানুষের সই বাধ্যতামূলক?
- বাসি ডেটার ঝুঁকি (Stale Data): সকাল 9টায় তৈরি হওয়া খসড়ায় সই করার মুহূর্তে দুপুর 12টায় যদি বাজারে শেয়ারের দাম বা ব্যালেন্স বদলে যায়, তবে কি পুরোনো তথ্যের ওপর ভিত্তি করে রিপোর্ট পাস হয়ে যাবে?
- মাঝপথে সার্ভার ক্র্যাশ বা রিস্টার্ট: দীর্ঘ প্রক্রিয়ার তৃতীয় ধাপে সার্ভার ক্র্যাশ করলে পুরো কাজ কি হারিয়ে যাবে, ডেটাবেস কি করাপ্ট হবে, নাকি নতুন প্রসেস এসে ঠিক যেখান থেকে কাজ থেমেছিল সেখান থেকেই আবার কাজ শুরু করতে পারবে?
এই বাস্তব ঝুঁকিগুলো সমাধান করতেই এই পর্বে আমরা রিপোর্ট জেনারেশনকে একটি শক্তিশালী ওয়ার্কফ্লো (Workflow)-এর শৃঙ্খলে বাঁধব। ওয়ার্কফ্লো মানে পুরো প্রক্রিয়াটিকে কয়েকটি সুনির্দিষ্ট ধাপে বিভক্ত করা, যেখানে প্রতিটি ধাপের সমাপ্তি ট্রানজ্যাকশন আকারে ডেটাবেসে স্থায়ীভাবে সংরক্ষিত থাকে। ফলে সিস্টেম ক্র্যাশ করলেও স্টেট হারিয়ে যায় না।
আমাদের পুরো আর্কিটেকচারের দুটি কেন্দ্রীয় ভিত্তি:
- মানুষের সই (Human-in-the-loop Approval): কৃত্রিম বুদ্ধিমত্তা কখনোই সরাসরি প্রোডাকশন ডেটাবেসে কিছু লিখতে পারবে না; AI শুধুমাত্র প্রস্তাব বা খসড়া তৈরি করবে, আর দায়িত্বশীল মানুষ তা যাচাই করে সই করবেন।
- একমাত্র সইয়ের দরজা (Single Gate to Approved Ledger): অনুমোদিত খাতার টেবিলে ডেটা প্রবেশের একটাই নিয়ন্ত্রিত গেটওয়ে থাকবে। সেই গেটওয়ে পার হতে প্রয়োজন হবে স্বাধীন দ্বিতীয় আরেকজন অনুমোদকের সই।
কোড: এই পর্বের শেষে কোডের অবস্থা github.com/alaminmain/foliolens-এর
part-07tag-এ। নিজের কাছে এনে চালাতে:git checkout part-07তারপরdotnet test। আগের পর্বের সঙ্গে তফাত দেখতে:git diff part-06 part-07।
কেন: report বানানো সহজ, তার পরের ব্যবস্থাই কঠিন
বাস্তব দৃশ্যপট কল্পনা করা যাক: সকাল 9টায় সিস্টেমের ইউজার রহিম দৈনিক রিভিউ প্রক্রিয়া চালু করলেন। পাঁচ মিনিটের মধ্যে পুরো পোর্টফোলিওর একটি চমৎকার ড্রাফট তৈরি হলো, যার প্রতিটি তথ্যের পেছনে সাইটেশন রয়েছে। এবার সেই তিনটি প্রশ্নের ইঞ্জিনিয়ারিং সমাধান দেখা যাক:
- ছাপার আগে কে দেখবে? রহিম নিজে যদি নিজের তৈরি খসড়া অনুমোদন করেন, তবে সেখানে স্বজনপ্রীতি বা ভুলের ঝুঁকি থেকেই যায়। তাই ফাইন্যান্সিয়াল সিস্টেমে Four-Eyes Principle আবশ্যক: যিনি রান রিকোয়েস্ট করেছেন, তিনি নিজে অনুমোদনকারী হতে পারবেন না। এখানে অনুমোদন করবেন করিম। করিম সই করলে তবেই রিপোর্টটি আমাদের মূল খাতায় (Approved Ledger) প্রবেশ করবে।
- দুপুরে দাম বদলালে সকালের রিপোর্ট কি কার্যকর থাকবে? এর সমাধান হলো ক্রিপ্টোগ্রাফিক Data Hash। খসড়া তৈরির মুহূর্তে পোর্টফোলিও তথ্যের একটি হ্যাশ সংরক্ষণ করা হবে। সই করার মুহূর্তে সিস্টেম লাইভ পোর্টফোলিওর বর্তমান হ্যাশের সাথে খসড়ার হ্যাশ মিলিয়ে দেখবে। সামান্য অমিল হলেই রিপোর্টটিকে সাথে সাথে
Staleচিহ্নিত করে পুনরায় ভেরিফিকেশনে পাঠানো হবে। - মাঝপথে সার্ভার ক্র্যাশ করলে কী হবে? রিপোর্টের প্রতিটি অগ্রগতিকে একটি ডিটারমিনিস্টিক State Machine দিয়ে নিয়ন্ত্রণ করা হবে এবং প্রতিটি স্টেট ট্রানজিশন SQLite ডেটাবেসে সেভ রাখা হবে। ফলে নতুন প্রসেস চালু হলেই অসমাপ্ত স্টেট থেকে কাজ পুনরায় শুরু করতে পারবে।
এখানে নতুন বিষয় একটাই: পাইপলাইনের একটি সংবেদনশীল ধাপ লার্জ ল্যাঙ্গুয়েজ মডেলের ওপর নির্ভরশীল, আর মডেল যেকোনো সময় অপ্রত্যাশিত ভুল করতে পারে। এ কারণেই চারপাশের সফটওয়্যার কন্ট্রোল সিস্টেমকে হতে হয় পাথরের মতো দৃঢ়।
ধারণা: workflow আগে, agent পরে
সফটওয়্যার ইঞ্জিনিয়ারিংয়ে রেলগাড়ি এবং ট্যাক্সির রূপকটি চমৎকারভাবে প্রযোজ্য। রেলগাড়ির লাইন আগে থেকেই মাটিতে পাতা থাকে; ফলে ট্রেনটি কোন কোন স্টেশনে থামবে, কতক্ষণ সময় লাগবে এবং কত খরচ হবে তা শতভাগ নিশ্চিতভাবে আগে থেকেই বলে দেওয়া সম্ভব। অন্যদিকে ট্যাক্সিতে গন্তব্য জানা থাকে ঠিকই, কিন্তু চালক জ্যাম বা রাস্তার পরিস্থিতি দেখে নিজেই তাৎক্ষণিকভাবে পথ বেছে নেন, ফলে সময় ও খরচ আগে থেকে নিখুঁতভাবে বলা কঠিন।
সফটওয়্যারের জগতে রেলগাড়ির মতো কাঠামোর নাম Workflow: এখানে প্রতিটি পদক্ষেপ কোডে স্পষ্টভাবে প্রোগ্রাম করা থাকে, মডেল কেবল একটি নির্দিষ্ট বিচ্ছিন্ন ধাপে টেক্সট বা খসড়া তৈরির কাজ করে। আর ট্যাক্সির মতো ব্যবস্থার নাম Agent: যেখানে মডেল নিজেই সিদ্ধান্ত নেয় সে কোন টুলটি ডাকবে এবং এরপর কোন ধাপে অগ্রসর হবে।
অ্যানথ্রপিকের বিখ্যাত গবেষণা প্রবন্ধ "Building effective agents"-এ ঠিক এই বিভাজনটি চমৎকারভাবে তুলে ধরা হয়েছে। ওয়ার্কফ্লোতে মডেল এবং টুল সর্বদা "predefined code paths"-এর মধ্য দিয়ে নিয়ন্ত্রিতভাবে চলে। এজেন্টে মডেল নিজেই নিজের প্রক্রিয়া ও টুলের ব্যবহার নির্ধারণ করে। সেই গবেষণার মূল পরামর্শ হলো: সর্বদা সবচেয়ে সরল ও নিয়ন্ত্রিত সমাধানটি আগে বেছে নিন; অতিপ্রয়োজনীয় না হলে অহেতুক জটিলতা বাড়াবেন না। কারণ ফুল-অটোনোমাস এজেন্টে টোকেন খরচ অস্বাভাবিক বৃদ্ধি পায় এবং ছোট ছোট সিদ্ধান্তহীনতার কারণে ভুলগুলো চক্রবৃদ্ধি হারে পুঞ্জীভূত হয় (Anthropic)।
ওয়ার্কফ্লো ও এজেন্টের মূল পার্থক্যগুলো নিচে তুলে ধরা হলো:
| বৈশিষ্ট্য | Workflow | Agent |
|---|---|---|
| পরবর্তী ধাপ কে নির্ধারণ করে | পূর্বনির্ধারিত C# কোড | লার্জ ল্যাঙ্গুয়েজ মডেল |
| মোট ধাপের সংখ্যা | ডেভেলপমেন্টের সময়ই নির্দিষ্ট | রানটাইমে পরিস্থিতির ওপর ভিত্তি করে গতিশীল |
| খরচ ও সময়ের পূর্বাভাস | অত্যন্ত সহজ ও নিয়ন্ত্রিত | অনির্দেশ্য, তাই কঠোর সীমা বেঁধে দেওয়া জরুরি |
| ভুল শনাক্তকরণ | প্রতিটি ধাপের শেষে ডিটারমিনিস্টিক validation | প্রতি কলের ইনপুট-আউটপুট গার্ড ও রান শেষে অডিট |
| ব্যবহারের আদর্শ ক্ষেত্র | নির্দিষ্ট প্রক্রিয়া: যেমন দৈনিক পোর্টফোলিও রিভিউ | উন্মুক্ত প্রশ্ন-উত্তর: যেমন অনির্ধারিত রিসার্চ কোয়েরি |
ফোলিওলেন্সে আমাদের দৈনিক রিভিউ একটি নিখুঁত ওয়ার্কফ্লো। অন্যদিকে পর্ব 4-এ পোর্টফোলিও সংক্রান্ত যেকোনো খোলা প্রশ্নের উত্তরে মডেল নিজেই টুল বেছে নিত, যা ধারণাগতভাবে এজেন্টের কাছাকাছি।
কোড 1: state machine, যার অবস্থা database-এ লেখা থাকে
এই পর্বের জন্য আমাদের সলিউশনে যুক্ত হয়েছে নতুন প্রকল্প FolioLens.Workflow (এবং তার টেস্ট প্রজেক্ট FolioLens.Workflow.Tests)। এটি আগের পর্বগুলোর Core, Extraction, Rag, Reports এবং Tools ব্যবহার করে। বাহ্যিক লাইব্রেরি হিসেবে শুধুমাত্র Microsoft.Data.Sqlite 10.0.14 ব্যবহার করা হয়েছে। হালকা ও সম্পূর্ণ ইন-প্রসেস ফাইল ডেটাবেস হওয়ায় কোনো অতিরিক্ত সার্ভিস ছাড়াই বাস্তব ফাইল ডেটাবেসে ট্রানজ্যাকশন টেস্ট করা যায়; এবং একই IReviewStore ইন্টারফেস বজায় রেখে ভবিষ্যতে সহজেই পোস্টগ্রেসে স্থানান্তর সম্ভব।
স্টেট মেশিন মানে হলো একটি নির্দিষ্ট রান বর্তমানে কোন অবস্থায় আছে তা সার্বক্ষণিক ডেটাবেসে রেকর্ড রাখা, এবং কোন স্টেট থেকে কোন স্টেটে যাওয়া বৈধ তার একটি অপরিবর্তনীয় তালিকা কোডে সংজ্ঞায়িত করা। উদাহরণস্বরূপ, যদি মাত্র তিনটি স্টেট থাকত:
DraftedথেকেAwaitingApproval: ভেরিফিকেশন টেস্ট পাস করলেই কেবল কোড এই ট্রানজিশন কার্যকর করে।AwaitingApprovalথেকেApproved: স্বাধীন দ্বিতীয় একজন মানুষ সই করলেই কেবল এখানে যাওয়া যায়।Draftedথেকে সরাসরিApproved: এই পথ তালিকায় নেই। কেউ বাইপাস করার চেষ্টা করলে সিস্টেম সাথে সাথেIllegalTransitionExceptionছুড়ে দেয়।
আমাদের আর্কিটেকচারে মোট 10টি স্টেট সংজ্ঞায়িত, এবং এই ট্রানজিশন নিয়মগুলো কোনো অগোছালো if-else ব্লক নয়, বরং সুস্পষ্ট ডেটা টেবিল হিসেবে ডিক্লেয়ার করা:
[(ReviewKind.DailyReview, ReviewState.Created)] = [ReviewState.FactsGathered],
[(ReviewKind.DailyReview, ReviewState.FactsGathered)] = [ReviewState.SourcesRetrieved],
[(ReviewKind.DailyReview, ReviewState.SourcesRetrieved)] = [ReviewState.Drafted],
[(ReviewKind.DailyReview, ReviewState.Drafted)] = [ReviewState.AwaitingApproval, ReviewState.VerificationFailed],
[(ReviewKind.DailyReview, ReviewState.AwaitingApproval)] = [ReviewState.Approved, ReviewState.Rejected, ReviewState.Expired, ReviewState.Stale],
[(ReviewKind.DailyReview, ReviewState.Stale)] = [ReviewState.AwaitingApproval, ReviewState.VerificationFailed],public static ReviewRun Move(ReviewRun run, ReviewState to, DateTimeOffset now)
{
if (!IsAllowed(run.Kind, run.State, to))
throw new IllegalTransitionException(run.Kind, run.State, to);
return run with { State = to, UpdatedAt = now };
}Createdথেকে শুরু করেFactsGathered,SourcesRetrievedএবংDraftedপর্যন্ত ধাপগুলো ক্রমানুসারে চলে।Draftedথেকে দুটি পথ: ভেরিফিকেশন পাস করলেAwaitingApproval, আর ব্যর্থ হলেVerificationFailed।AwaitingApprovalথেকে চারটি পথ: মানুষ সই করলেApproved, বাতিল করলেRejected, সময় পেরিয়ে গেলেExpired, এবং অনুমোদনকালে ডেটা বদলে গেলেStale।Staleঅবস্থা থেকে সরাসরি কোনো সই নেওয়া যায় না; এটি আবার ভেরিফায়ার দিয়ে পরীক্ষা করে পাস করলে পুনরায়AwaitingApproval-এ ফিরে আসে, নতুবাVerificationFailed-এ চলে যায়।
Move ফাংশনটি অনুমোদিত তালিকার বাইরে যেকোনো চাল আটকে দেয়। ফলে সই এড়িয়ে কেউ কোনো অবস্থাতেই রিপোর্ট পাস করাতে পারে না।
প্রতিটি ধাপ এক লেখায়
স্টেট পরিবর্তনের সাথে সাথে একটি অপরিবর্তনীয় ট্রেইল (Audit Trail) লগ লেখাও বাধ্যতামূলক। ট্রেইল হলো প্রতিটি পরিবর্তনের ঐতিহাসিক দলিল: কে, কখন, কোন পরিস্থিতিতে কী পরিবর্তন করলেন। যদি স্টেট পরিবর্তন এবং ট্রেইল রাইট দুটি আলাদা ডেটাবেস অপারেশনে ঘটে, তবে মাঝপথে ক্র্যাশ করলে ডেটাবেসের স্টেট বদলে যাবে, কিন্তু অডিট ট্রেইলে কোনো প্রমাণ থাকবে না।
এই অখণ্ডতা নিশ্চিত করতে উভয় অপারেশনকে একটি একক ডেটাবেস ট্রানজ্যাকশনের মধ্যে আনা হয়েছে। একই সাথে কনকারেন্সি নিয়ন্ত্রণ করতে Optimistic Concurrency Control (Version Check) ব্যবহার করা হয়েছে:
await using var tx = c.BeginTransaction(deferred: false);
var stored = next with { Version = expectedVersion + 1 };
int changed;
await using (var cmd = Command(c, tx, "UPDATE runs SET version = $new, state = $state, json = $json WHERE id = $id AND version = $expected"))
{
// ... parameters
changed = await cmd.ExecuteNonQueryAsync(cancellationToken);
}
if (changed == 0) return null; // someone else moved first; the transaction rolls back on dispose
var written = await InsertTrail(c, tx, entry, cancellationToken);
await tx.CommitAsync(cancellationToken);
return new StoreResult(stored, written);BeginTransaction(deferred: false)শুরুতেই লেখার তালা নেয়। SQLite-এর doc বলে,BEGIN IMMEDIATEঅন্য কোনো রাইটারকে একই সাথে ঢুকতে দেয় না (SQLite Transaction, Connection Strings)।UPDATE runs SET ... WHERE id = $id AND version = $expectedশর্তটিই পুরো স্টেট মেশিনের সবচেয়ে শক্তিশালী সুরক্ষা কবচ। যদি অন্য কেউ ইতিমধ্যে স্টেট বা ভার্সন পরিবর্তন করে ফেলে, তবে এই কুয়েরিতে 0টি রো আপডেট হবে, ট্রানজ্যাকশন রোলব্যাক হবে এবং কনকারেন্ট রাইট সম্পূর্ণ নিরাপদ থাকবে।
অডিট ট্রেইল যাতে কেউ ডেটাবেসে ঢুকে ইচ্ছাকৃতভাবে পরিবর্তন বা মুছে ফেলতে না পারে, সেজন্য SQLite লেভেলেই একটি ট্রিগার বসানো হয়েছে:
CREATE TRIGGER IF NOT EXISTS trail_no_update BEFORE UPDATE ON trail
BEGIN SELECT RAISE(ABORT, 'the trail is append-only'); END;এখানে UPDATE-এরটা দেখানো, DELETE-এরটাও একই রকম। Trail বদলাতে গেলে বার্তা আসে "the trail is append-only" (CREATE TRIGGER)।
খোলা সুতো: trail-এ রহিম আর করিমের নাম লেখা থাকে, কিন্তু trigger ফেলে নাম বদলে দেওয়া যায়। পর্ব 8-এ এই ট্রেইলের ওপর ক্রিপ্টোগ্রাফিক হ্যাশ চেইন ও ডিজিটাল সিগনেচার যুক্ত করে সম্পূর্ণ টেম্পার-প্রুফ অডিট লগ তৈরি করা হবে।
চারটা ধাপ, প্রতিটা আলাদা করে save করা
আমাদের রানার ক্লাস AdvanceAsync লুপের মাধ্যমে চারটি প্রাথমিক ধাপ সম্পন্ন করে। প্রতিটি ধাপ স্বাধীনভাবে এক্সিকিউট হয় এবং ফলাফল সাথে সাথে ডেটাবেসে ট্রানজ্যাকশনসহ সেভ হয়:
switch (run.State)
{
case ReviewState.Created:
await GatherFactsAsync(run, payload, ct);
break;
case ReviewState.FactsGathered:
await RetrieveSourcesAsync(run, payload, ct);
break;
case ReviewState.SourcesRetrieved:
await DraftAsync(run, payload, ct);
break;
case ReviewState.Drafted:
ticket = (await VerifyAsync(run, payload, ct)).Ticket;
break;
default:
return new ReviewProgress(run, ticket); // waiting for a person, or finished
}প্রতিটি ধাপ সফলভাবে শেষ হওয়ার পরই কেবল পরবর্তী ধাপের জন্য স্টেট আপডেট হয়। যদি কোনো কারণে প্রসেসটি মাঝপথে ক্র্যাশ করে, তবে পরবর্তী রিস্টার্টে সিস্টেম ডেটাবেস থেকে সর্বশেষ সফল স্টেটটি রিড করে ঠিক তার পরের ধাপ থেকে এক্সিকিউশন শুরু করতে পারে।
কোড 2: সইয়ের দরজা
অনুমোদনের গেটওয়ে ক্লাস ApprovalGate হলো আমাদের সবচেয়ে গুরুত্বপূর্ণ কন্ট্রোল মেকানিজম। এটি মূলত দুটি অত্যন্ত সংবেদনশীল দায়িত্ব পালন করে:
- Four-Eyes Principle নিশ্চিতকরণ: যে ইউজার রানটি শুরু করেছিলেন (
run.RequestedBy), তিনি কখনোই নিজে সেই রিপোর্ট অনুমোদন করতে পারবেন না। - Stale Data প্রতিরোধ: খসড়া তৈরির সময়ের পোর্টফোলিও হ্যাশ (
run.DataHash) এবং বর্তমান লাইভ পোর্টফোলিওর হ্যাশ হুবহু না মিললে অনুমোদন বাতিল করে স্টেটকেStale-এ পাঠিয়ে দেওয়া।
if (who == run.RequestedBy)
{
await _mover.NoteAsync(run.Id, who, "approval_refused", run.ContentHash, "the author cannot approve their own draft", run.State.ToString(), ct);
return new(ApprovalOutcome.SelfApprovalRefused, run, "The author of a draft cannot approve it.");
}
if (!Hashing.TokenMatches(token, run.TokenHash))
{
await _mover.NoteAsync(run.Id, who, "approval_refused", run.ContentHash, "wrong or already used token", run.State.ToString(), ct);
return new(ApprovalOutcome.BadToken, run, "The approval token is wrong or no longer valid.");
}বাসি তথ্য ধরার অংশটিও একইভাবে সুনির্দিষ্ট কারণ ও সময়সহ অডিট ট্রেইলে লগ সংরক্ষণ করে:
if (_kinds[run.Kind].CurrentBasisHash() != run.BasisHash)
{
var stale = await _mover.MoveAsync(run, ReviewState.Stale, "gate", "stale_detected", run.ContentHash,
"the facts changed after drafting; verify again before signing", r => r with { TokenHash = null }, ct);
if (stale is null) continue;
return new(ApprovalOutcome.StaleFacts, stale, "The facts changed after this draft was written. Verify it again.");
}বাসি report: বাতিল নয়, আবার যাচাই
পোর্টফোলিওতে নতুন কোনো ট্রেড এক্সিকিউট হলে বা শেয়ারের দাম পরিবর্তিত হলে সকালের খসড়াটির ডেটা বাসি বা স্টেল হয়ে যায়। কিন্তু এর অর্থ এই নয় যে পুরো ড্রাফটটিকে ফেলে দিতে হবে। ApprovalGate এটিকে সাময়িকভাবে Stale মার্ক করে পুনরায় সাইটেশন ভেরিফায়ারের কাছে পাঠায়। যদি পরিবর্তিত ডেটার সাথেও ড্রাফটের সমস্ত সাইটেশন ও হিসাব শতভাগ সামঞ্জস্যপূর্ণ থাকে, তবে রিপোর্টটি পুনরায় AwaitingApproval-এ ফিরে আসে; আর কোনো সংখ্যায় অসংগতি দেখা দিলে তা সরাসরি VerificationFailed-এ স্থানান্তরিত হয়।
একমাত্র লেখার পথ
অনুমোদিত রিপোর্ট সংরক্ষণের টেবিলে (approved_reports) যাতে কোনো ব্যাকডোর বা সরাসরি ইনসার্ট না হতে পারে, সেজন্য ডেটাবেস লেভেলে একটি কঠোর ট্রিগার স্থাপন করা হয়েছে:
public interface IBookOfRecord
{
Task<bool> RecordTradeAsync(string idempotencyKey, Trade trade, string approvedBy, CancellationToken cancellationToken = default);
Task<bool> PublishReportAsync(string idempotencyKey, string title, string markdown, string approvedBy, CancellationToken cancellationToken = default);
}এই ট্রিগারের ফলে শুধুমাত্র স্টেট মেশিনের Approved স্টেট ছাড়া অন্য কোনো উপায়ে এই টেবিলে কোনো রেকর্ড ইনসার্ট করা প্রযুক্তিগতভাবেই অসম্ভব।
IApprovalGate ইন্টারফেসের চুক্তি:
foreach (var assembly in new[] { typeof(PortfolioTools).Assembly })
{
var references = assembly.GetReferencedAssemblies().Select(a => a.Name).ToList();
Assert.DoesNotContain("FolioLens.Workflow", references);
}OWASP-এর LLM-ঝুঁকির তালিকায় "Excessive Agency" মানে model-কে দরকারের বেশি ক্ষমতা দেওয়া। প্রতিকার-তালিকায় প্রথম পরামর্শ: মানুষের অনুমোদন ছাড়া কোনো আসল পরিবর্তন নয় (OWASP LLM06, পর্ব 9)।
সুতো বাঁধা: পর্ব 4-এ বলা হয়েছিল, tool-গুলো শুধু পড়ে, আর state বদলানোর পথ থাকবে একটাই। সেই একমাত্র পথ এই সইয়ের দরজা। এই দরজায় বসেই পর্ব 9-এর MCP সার্ভারের টুলগুলো নিয়ন্ত্রিত হবে, এবং লেনদেনের খসড়াও (পর্ব 2-এ model নোট পড়ে যে খসড়া বানাত) এই একই সইয়ের নিয়ম মেনে খাতায় উঠবে।
কোড 3: সীমা-বাঁধা agent loop
দৈনিক রিভিউ যেখানে একটি স্থির ওয়ার্কফ্লো, সেখানে পোর্টফোলিও সংক্রান্ত মুক্ত প্রশ্নের উত্তর দিতে আমাদের প্রায়ই একটি ডায়নামিক এজেন্ট লুপ চালাতে হয়। পর্ব 4-এ FunctionInvokingChatClient এই loop আড়ালে চালাত, ধাপ-সীমা ছিল MaximumIterationsPerRequest (Microsoft Learn)।
কিন্তু প্রোডাকশন-গ্রেড এজেন্টে কেবল সর্বোচ্চ ধাপ বেঁধে দেওয়াই যথেষ্ট নয়। একটি বেপরোয়া মডেলকে কঠোর নিয়ন্ত্রণে রাখতে আমাদের AgentLimits কাঠামোতে চারটি স্পষ্ট প্যারামিটার সংজ্ঞায়িত:
- MaxSteps (সর্বোচ্চ পদক্ষেপ): মডেল সর্বোচ্চ কতবার টুল কল করতে পারবে (ডিফল্ট: 6)।
- MaxIdenticalCalls (চক্র শনাক্তকরণ): একই প্যারামিটার দিয়ে একই টুল পরপর কতবার কল করা যাবে (ডিফল্ট: 2)। মডেল যদি একই ভুল প্যারামিটার দিয়ে বারবার একই টুল কল করতে থাকে, তবে সিস্টেম ইনফিনিট লুপ শনাক্ত করে সাথে সাথে এক্সিকিউশন থামিয়ে দেয়।
- MaxRetriesPerTool (টুল ব্যর্থতার সহনশীলতা): কোনো টুল নেটওয়ার্ক বা ডেটাবেস এরর দিলে সর্বোচ্চ কতবার রিট্রাই করা যাবে (ডিফল্ট: 2)।
- TotalBudgetTokens (টোকেন বাজেট): পুরো এজেন্ট সেশনের জন্য মোট টোকেন খরচের ঊর্ধ্বসীমা।
এজেন্ট লুপের C# কোর বাস্তবায়ন:
// Exit 1-3: ceilings, checked BEFORE spending anything more.
if (steps >= _limits.MaxSteps) return Stop(StopReason.MaxSteps);
if (tokens >= _limits.MaxTotalTokens) return Stop(StopReason.TokenBudget);
if (_limits.MaxCost is { } maxCost && cost >= maxCost) return Stop(StopReason.CostBudget);
var response = await chat.GetResponseAsync(messages, options, ct);
steps++;
inputTokens += response.Usage?.InputTokenCount ?? 0;
outputTokens += response.Usage?.OutputTokenCount ?? 0;
tokens = inputTokens + outputTokens;
cost = CostOf(inputTokens, outputTokens);
messages.AddRange(response.Messages);এখানে মডেলের প্রতিটি পদক্ষেপের জন্য একটি নির্দিষ্ট টোকেন ও ল্যাটেন্সি বাজেট সংরক্ষিত থাকে। কোনো সীমাই মডেলের মনগড়া সিদ্ধান্তের ওপর ছেড়ে দেওয়া হয়নি; বরং পর্ব 1-এর প্রথম নীতির মতোই কোড সর্বদা মডেলের ওপর সম্পূর্ণ নিয়ন্ত্রণ বজায় রাখে।
দৃশ্যপট: চোদ্দটা ঘটনা, প্রতিটা test-এ চলে
আমাদের পুরো টেস্ট স্যুট FolioLens.Workflow.Tests-এ মোট 14টি বাস্তবমুখী দৃশ্যপট অটোমেটেড টেস্টের আওতায় আনা হয়েছে:
| দৃশ্যপট | পরীক্ষা | ফলাফল |
|---|---|---|
| 1 | সম্পূর্ণ সুখী পথ: তৈরি থেকে করিমের অনুমোদন | Approved, অডিট ট্রেইলে 5টি রেকর্ড |
| 2 | সেলফ-অ্যাপ্রুভাল চেষ্টা: রহিম নিজেই সই করতে চাইলেন | SelfApprovalForbiddenException |
| 3 | রিজেকশন: করিম কারণসহ রিপোর্ট বাতিল করলেন | Rejected, কারণ ট্রেইলে লিপিবদ্ধ |
| 4 | মেয়াদোত্তীর্ণ: নির্ধারিত সময়ে কেউ সই করলেন না | Expired, ব্যাকগ্রাউন্ড জব দ্বারা চিহ্নিত |
| 5 | ডুপ্লিকেট রান: একই দিনে একই পোর্টফোলিওর জন্য দ্বিতীয় রান | ইডেমপোটেন্টলি বিদ্যমান রান ফেরত দেয় |
| 6 | যাচাই ব্যর্থতা: খসড়ায় ভুয়া উদ্ধৃতি বা ভুল সংখ্যা | VerificationFailed, গেটওয়েতে পৌঁছায় না |
| 7 | ইনভ্যালিড ট্রানজিশন: খসড়া থেকে সরাসরি অ্যাপ্রুভ করার চেষ্টা | IllegalTransitionException |
| 8 | কনকারেন্ট রাইট: দুজন রিভিউয়ার একই সাথে সই করার চেষ্টা করলেন | একজন সফল, অন্যজনের ট্রানজ্যাকশন সেফলি রিজেক্টেড |
| 9 | বাসি তথ্য: ড্রাফট তৈরির পর নতুন ট্রেড এক্সিকিউট হলো | Stale, রি-ভেরিফিকেশন ট্রিগার |
| 10 | বাসি তথ্যের রি-ভেরিফিকেশন পাস | নতুন ডেটায় সাইটেশন ঠিক থাকায় পুনরায় AwaitingApproval |
| 11 | মাঝপথে সার্ভার ক্র্যাশ: রানার বন্ধ হয়ে যাওয়া | রিস্টার্টের পর সর্বশেষ সেভড স্টেট থেকে সফল রিকভারি |
| 12 | এজেন্টের ইনফিনিট লুপ: মডেল একই টুল বারবার কল করছে | RepeatedCall শনাক্ত করে লুপ সমাপ্ত |
| 13 | বাজেট নিঃশেষ: মডেল অতিরিক্ত টোকেন খরচ করে ফেলল | BudgetExhausted দিয়ে নিয়ন্ত্রিত প্রস্থান |
| 14 | টুল ক্র্যাশ সহনশীলতা: টুল এক্সেপশন ছুড়ে দিলে নিয়ন্ত্রিত হ্যান্ডলিং | MaxRetriesPerTool শেষে মার্জিত ব্যর্থতা |
দৃশ্যপট 1: সুখী পথের trail
একটি সফল এক্সিকিউশনে অডিট ট্রেইলটি দেখতে ঠিক নিচের মতো স্বচ্ছ ও নিখুঁত হয়:
1 rahim created ->Created | আলফা টেকের লভ্যাংশ ও রেকর্ড ডেট; হিসাব রক্ষণাবেক্ষণ ফি
2 workflow facts_gathered Created->FactsGathered | 7 trades, as of 2026-10-30
3 workflow sources_retrieved FactsGathered->SourcesRetrieved | alfa-dividend#0,record-date#1,alfa-dividend#1,namuna-fees-2026#0,namuna-fees#0,gama-plant#0
4 model drafted SourcesRetrieved->Drafted | 2 accepted, 0 rejected, 1 round(s)
5 workflow verified Drafted->AwaitingApproval | 2 claims verified; signature needed before 2026-10-31T09:00:00.0000000+00:00
6 rahim approval_refused AwaitingApproval->AwaitingApproval | the author cannot approve their own draft
7 karim approval_refused AwaitingApproval->AwaitingApproval | wrong or already used token
8 karim approved AwaitingApproval->Approved | signed by karim
9 gate published Approved->Approved | written to the recordদৃশ্যপট 9: বাসি তথ্য
খসড়া তৈরির পর ব্যাকগ্রাউন্ডে আলফা টেকের নতুন ট্রেড যুক্ত হলে অ্যাপ্রুভাল গেটওয়ের লগ:
6 gate stale_detected AwaitingApproval->Stale | the facts changed after drafting; verify again before signing
7 salma reverify_failed Stale->VerificationFailed | পোর্টফোলিওর মোট বাজারমূল্য ১১২৭৬০ টাকা। -> fact:portfolio.market_value: হিসাবের মান 115010.00, দাবিতে 112760।দৃশ্যপট 11: মাঝপথে crash
ধাপ 2 (SourcesRetrieved) শেষ হওয়ার ঠিক পরেই প্রসেসটি ক্র্যাশ করানো হয়। নতুন একটি রানার ইনস্ট্যান্স ইনস্ট্যানশিয়েট করে রান আইডি দিলে দেখা যায়, পূর্ববর্তী ধাপগুলো দ্বিতীয়বার না চালিয়ে সরাসরি ধাপ 3 (Drafted) থেকে নির্বিঘ্নে কাজ সম্পন্ন হয়।
দৃশ্যপট 12 ও 13: infinite loop আর budget
একটি মডেল যখন বারবার একই আর্গুমেন্ট দিয়ে holding_quantity টুলটি কল করতে থাকে, আমাদের AgentLoop দ্বিতীয় পুনরাবৃত্তির পরই এক্সিকিউশন থামিয়ে দেয়। একইভাবে নির্ধারিত টোকেন লিমিট পার হওয়ার সাথে সাথে বাজেট গার্ড সিস্টেমকে অতিরিক্ত ক্লাউড বিলের হাত থেকে রক্ষা করে।
বাড়তি দৃশ্য: দ্বিতীয় বিক্রি, আটকানো
একটি সংবেদনশীল আর্থিক টেস্ট: একই পোর্টফোলিওর সমস্ত শেয়ার বিক্রির খসড়া তৈরি হয়েছে, কিন্তু সই হওয়ার আগেই অন্য আরেকজন ব্রোকার সেই একই শেয়ার বিক্রি করে ফেলেছেন। সইয়ের মুহূর্তে ডেটা হ্যাশ অমিল হওয়ায় গেটওয়ে সাথে সাথে লেনদেন আটকে দেয় এবং পোর্টফোলিওকে ডাবল-স্পেন্ডিং দুর্যোগ থেকে বাঁচিয়ে দেয়।
মাপা: কী কী test করা হয়েছে
- স্টেট মেশিনের প্রতিটি ট্রানজিশন পাথ ম্যাট্রিক্স টেস্ট দ্বারা আচ্ছাদিত।
- SQLite ডেটাবেস ট্রানজ্যাকশন এবং
IMMEDIATEলকিং বাস্তব ফাইলের ওপর কনকারেন্ট থ্রেড চালিয়ে ভেরিফাইড। - 14টি এন্ড-টু-এন্ড টেস্ট সম্পূর্ণ স্বয়ংক্রিয়ভাবে সিআই পাইপলাইনে এক্সিকিউট হয়।
তবে মনে রাখা জরুরি: টেস্ট স্যুটে ব্যবহৃত মডেল রেসপন্স ছিল FakeChatClient-এর স্ক্রিপ্টেড উত্তর। বাস্তব প্রোডাকশন মডেল ঠিক কত ঘন ঘন রিপিটেড কল করে বা সাইটেশনে ভুল করে, তা পরিমাপ করতে হবে পর্ব 3-এর ইভ্যালুয়েশন টেস্ট স্যুট দিয়ে।
production-এ কী ভাঙে
বাস্তব প্রোডাকশনে সিস্টেম ডেপ্লয় করার আগে এই গুরুত্বপূর্ণ ঝুঁকিগুলো বিবেচনায় নিতে হবে:
- কনকারেন্ট ওয়ার্কার ও ডুপ্লিকেট এক্সিকিউশন: একাধিক ব্যাকগ্রাউন্ড ওয়ার্কার যদি একই সাথে একটি পেন্ডিং রান প্রসেস করার চেষ্টা করে, তবে মডেল একাধিকবার কল হয়ে টোকেন খরচ দ্বিগুণ হতে পারে। প্রতিকার: ডেটাবেসে ওয়ার্কার লিজ বা এক্সক্লুসিভ লক মেকানিজম রাখা (পর্ব 10-এ বিস্তারিত ড্যাশবোর্ড ও ট্রেসিং রয়েছে)।
- লং-রানিং ট্রানজ্যাকশন ও ডেটাবেস ডেডলক: মডেল কল বা এক্সটার্নাল এপিআই রিকোয়েস্ট কখনোই ডেটাবেস ট্রানজ্যাকশনের ভেতরে রাখা যাবে না। ট্রানজ্যাকশন কেবল স্টেট রিড এবং রাইটের সময় কয়েক মিলিসেকেন্ডের জন্য খুলবে।
- অনুমোদনের সময়সীমা (Approval Timeout): মানুষের সইয়ের জন্য ড্রাফট বছরের পর বছর ঝুলিয়ে রাখা যাবে না। একটি নির্দিষ্ট সময়ের পর (যেমন: 24 ঘণ্টা) ব্যাকগ্রাউন্ড জবের মাধ্যমে পেন্ডিং ড্রাফটগুলোকে
Expiredকরে দেওয়া বাঞ্ছনীয়। - ইউজার অথেনটিকেশন ও ভূমিকা: অ্যাপ্রুভাল গেটওয়েকে অবশ্যই এন্টারপ্রাইজ আইডেন্টিটি প্রোভাইডার (OAuth/OIDC)-এর সাথে যুক্ত করতে হবে, যাতে ব্যবহারকারীর নাম ও ভূমিকা কোনোভাবেই স্পুফ করা না যায়।
অনুশীলন
AgentLimits-এMaxIdenticalCalls5 করে দৃশ্যপট 12 চালান। পর্যবেক্ষণ করুন: লুপটি কিRepeatedCall-এ থামে নাকিMaxSteps-এ?WorkflowOptions-এApprovalWindowকমিয়ে 1 মিনিট করুন এবং টেস্টে ঘড়ি 61 সেকেন্ড এগিয়ে দিয়ে দেখুনExpireDueAsyncঠিক কীভাবে মেয়াদ শেষ করে।ApprovalGate.ApproveAsync-এ চার-চোখের নীতি (who == run.RequestedBy) সাময়িকভাবে কমেন্ট করে টেস্ট চালান। কোন কোন টেস্ট ফেইল করে তা নোট করুন।- একটি নতুন
ReviewKind(যেমন:PriceCorrection) যুক্ত করুন এবং স্টেট ট্রানজিশন টেবিলে প্রয়োজনীয় রুটগুলো কনফিগার করুন। ToolFailedটেস্টেMaxRetriesPerTool = 0সেট করে রিট্রাই মেকানিজমের আচরণ লক্ষ্য করুন।
মনে রাখুন: AI প্রস্তাব করে, মানুষ সই করে। Report খাতায় ঢোকার পথ একটাই, সেই সইয়ের দরজা। দরজা খোলা-বন্ধ করার সিদ্ধান্ত কোড নেয়, model নয়।
যাচাইয়ের অবস্থা
Workflow, দরজা আর agent loop-এর সব কোড net10.0 target-এ test করা। Model সব জায়গায় FakeChatClient-এর scripted উত্তর। Database test আসল SQLite file-এ চলে, আর শেষে file মুছে ফেলা হয়। আসল model কেমন খসড়া করবে বা কতবার loop ঘোরাবে, এই পর্ব তা বলে না। সেটা evaluation দিয়ে মাপুন। পরিচয় যাচাই (authentication) এই কোডে নেই, দরজা ধরে নেয় বাইরে থেকে আসা নাম ঠিক।
সূত্র
- Anthropic: Building effective agents
- OWASP GenAI: LLM06 Excessive Agency
- SQLite: Transaction (BEGIN IMMEDIATE)
- SQLite: CREATE TRIGGER (RAISE)
- Microsoft Learn: FunctionInvokingChatClient.MaximumIterationsPerRequest
- Microsoft Learn: Microsoft.Data.Sqlite connection strings
পরের পর্ব
সইয়ের দরজা পাহারায় আছে, কিন্তু model-এর কাছে যা যায়, তা দরজার আগেই পৌঁছায়: ALFA-র নোট, খুঁজে পাওয়া নথি, ব্যবহারকারীর প্রশ্ন। কেউ যদি নথির ভেতরে লুকিয়ে model-কে হুকুম দিয়ে রাখে? পর্ব 8-এর সূত্র তিন প্রহরী: model-এর আগে input-এ, মাঝখানে tool-এ, শেষে output-এ, তিন জায়গায় পাহারা বসবে। সঙ্গে আসবে এই trail-এর ওপর hash chain-এর audit log, আর একটা red-team set (নিজেদের বানানো আক্রমণের তালিকা), যা দেখাবে কোন আক্রমণ কে ঠেকাল, কোনটা পার হয়ে গেল।
সিরিজের পথ: ← পর্ব 6: পাদটীকা · সিরিজের মানচিত্র · পর্ব 8: তিন প্রহরী →


