Custom agent eval-এ trace গেলেও ভুল field দিলে score হবে না

AgentCore Evaluations-এ custom framework-এর trace পৌঁছানোই যথেষ্ট নয়। Generic evaluation-এর জন্য instrumentation scope স্বীকৃত prefix দিয়ে শুরু হতে হবে, span-এ তার operation চেনানোর attribute থাকতে হবে এবং prompt, response ও tool data নির্ধারিত field-এ দিতে হবে; প্রয়োজনীয় content না পেলে evaluator interaction পুনর্গঠন করে score দিতে পারে না।

ন্যূনতম কাঠামো হলো একটি user turn-এর জন্য agent span, প্রতিটি model call-এর জন্য inference span এবং ব্যবহৃত প্রতিটি tool-এর জন্য tool span। OpenTelemetry বা OpenInference—যেটি নেবেন, সেই span-এর scope, identifying attribute ও content field একই convention অনুযায়ী সাজাতে হবে।

প্রথম gate: tracer-এর scope স্বীকৃত করুন

নিজস্ব tracer-এর scope mycompany.agent.tracing হলে span CloudWatch-এ export হতে পারে, কিন্তু AgentCore-এর generic path সেটি পড়বে না। OpenTelemetry convention-এর scope শুরু হতে হবে opentelemetry.instrumentation. দিয়ে; OpenInference-এর ক্ষেত্রে prefix হবে openinference.instrumentation.। উদাহরণ হিসেবে custom OpenTelemetry instrumentation-এর নাম হতে পারে opentelemetry.instrumentation.acme_agent।

Scope কোনো সাধারণ span attribute নয়। OpenTelemetry-এর instrumentation scope ব্যাখ্যা অনুযায়ী tracer নেওয়ার সময় scope নির্ধারিত হয় এবং সেই tracer থেকে তৈরি telemetry record-এ তা যুক্ত থাকে। তাই span-এ নিজের তৈরি scope.name attribute বসানোর বদলে tracer বা instrumentation library তৈরির সময় সঠিক নাম দিতে হবে।

সব matching prefix-ও agent telemetry হিসেবে গৃহীত হয় না। HTTP client, FastAPI, MCP ও botocore-এর মতো transport বা infrastructure instrumentation generic evaluation থেকে বাদ থাকে, যাতে সেগুলোর span ভুল করে agent, inference বা tool operation না হয়। Agent-এর প্রয়োজনীয় span তাই agent instrumentation-এর নিজস্ব tracer দিয়েই তৈরি করুন।

দ্বিতীয় gate: span-এর operation স্পষ্ট করুন

AgentCore span name দেখে operation অনুমান করে না। AWS-এর generic framework specification বলছে, স্বীকৃত identifying attribute না থাকলে service span-টি বাদ দেয়; একই specification scope prefix, classification এবং content extraction-এর গ্রহণযোগ্য field-ও নির্ধারণ করে।

• OpenTelemetry agent span: gen_ai.operation.name = invoke_agent; fallback হিসেবে traceloop.span.kind = workflow।
• OpenTelemetry inference span: gen_ai.operation.name = chat; operation না থাকলে llm.request.type = chat fallback হতে পারে।
• OpenTelemetry tool span: gen_ai.operation.name = execute_tool; fallback হিসেবে traceloop.span.kind = tool।
• OpenInference agent span: openinference.span.kind = AGENT বা CHAIN; inference-এর জন্য LLM এবং tool-এর জন্য TOOL।

Parent-child সম্পর্ক বা বর্ণনামূলক span name এই attribute-এর বিকল্প নয়। যে span evaluator-কে পড়াতে চান, সেই span-এই সংশ্লিষ্ট identifying attribute দিতে হবে।

ন্যূনতম OpenTelemetry field map

একটি শর্তসাপেক্ষ উদাহরণে ব্যবহারকারী পণ্যের মজুত জানতে চায়, agent inventory tool ডেকে উত্তর দেয়। এই turn-এ top-level agent span request ও final response বহন করবে; inference span model-এর input-output এবং tool span tool execution-এর data রাখবে।

• Agent span-এ gen_ai.operation.name = invoke_agent দিন। User prompt রাখুন gen_ai.task.input-এ এবং final response রাখুন gen_ai.task.output-এ। Split telemetry ব্যবহৃত হলে service আগে correlated event record-এর body.input ও body.output পরীক্ষা করে।
• Inference span-এ gen_ai.operation.name = chat দিন। Input messages রাখুন gen_ai.input.messages-এ, output messages gen_ai.output.messages-এ এবং প্রয়োজন হলে system instruction gen_ai.system_instructions-এ রাখুন।
• Tool span-এ gen_ai.operation.name = execute_tool দিন। Tool-এর নাম gen_ai.tool.name, arguments gen_ai.tool.call.arguments এবং result gen_ai.tool.call.result-এ থাকবে।
• Inference span-এ ঘোষিত tool schema convention অনুযায়ী tool-definition attribute-এ serialize করুন। Model-এর tool request ও execution span মেলাতে একই gen_ai.tool.call.id ব্যবহার করুন।

নিজস্ব request.payload.messages বা অন্য nested envelope-এ data লুকিয়ে রাখলে AgentCore framework-specific object খুলে প্রয়োজনীয় value বের করবে না; documented location-এর value string হিসেবে নেয়। Convention attributes দেওয়া সম্ভব না হলে agentcore.invocation.user_prompt ও agentcore.invocation.agent_response দিয়ে top-level turn মূল্যায়ন করা যায়, তবে এতে inference ও tool span coverage পাওয়া যায় না।

OpenInference নিলে content key-ও বদলান

শুধু scope prefix বদলে OpenTelemetry-এর field রেখে দিলে OpenInference path সম্পূর্ণ data পাবে না। Agent span-এর prompt রাখুন input.value-এ এবং response রাখুন output.value-এ। Inference messages-এর জন্য llm.input_messages.0.message.role, llm.input_messages.0.message.content এবং একই ধরনের llm.output_messages indexed attributes ব্যবহার করুন।

Tool span-এ নামের field tool.name, arguments-এর field input.value এবং result-এর field output.value। Inference span-এ available tool schema রাখা যায় llm.tools.0.tool.json_schema ধরনের indexed attribute-এ। একাধিক message বা tool হলে index শূন্য থেকে ধারাবাহিকভাবে বাড়ান।

অর্থাৎ convention নির্বাচন span-ভিত্তিক পূর্ণ contract: ওই span-এর scope বলে AgentCore কোন schema ব্যবহার করবে, operation attribute বলে span-এর ভূমিকা এবং content key বলে কোন value evaluator পাবে। এক convention-এর scope-এর সঙ্গে অন্যটির field মেশালে transport সফল হলেও extraction অসম্পূর্ণ থাকতে পারে।

CloudWatch-এ trace দেখা evaluation-ready হওয়ার প্রমাণ নয়

AWS-এর framework-agnostic evaluation walkthrough অনুযায়ী AgentCore Evaluations CloudWatch থেকে span ও event record নিয়ে session.id দিয়ে session এবং trace_id দিয়ে একটি user turn পুনর্গঠন করে। AgentCore Runtime-এ span-এর session ID-কে invocation-এর runtimeSessionId-এর সঙ্গে মিলতে হয়; Runtime-এর বাইরে telemetry পাঠালে এই correlation instrumentation ও exporter configuration-এ নিশ্চিত করতে হবে।

Unified observability-তে message content ও span একই per-agent log group-এ থাকে। পুরোনো split configuration-এ span shared aws/spans log group-এ থাকলেও message content সংশ্লিষ্ট agent log group-এর correlated event record-এ থাকতে পারে। Data source শুধু aws/spans নিলে classification সফল হলেও message content খালি ফেরে এবং response-quality evaluator error দেয়—এটাই trace দেখা সত্ত্বেও score না পাওয়ার একটি সরাসরি কারণ।

Score না এলে এই ক্রমে diagnosis করুন

1. আসল scope দেখুন: exported record-এর instrumentation scope স্বীকৃত prefix দিয়ে শুরু হয়েছে কি না পরীক্ষা করুন। একই নামের custom span attribute দেখে সিদ্ধান্ত নেবেন না।
2. Excluded scope শনাক্ত করুন: span-টি HTTP client, web framework, MCP বা AWS SDK instrumentation থেকে এসেছে কি না দেখুন। এলে agent instrumentation-এর tracer দিয়ে প্রয়োজনীয় operation span তৈরি করুন।
3. Role মিলিয়ে নিন: agent, inference ও tool span-এর প্রত্যেকটিতে নির্বাচিত convention-এর exact identifying attribute ও value আছে কি না দেখুন।
4. Content location পরীক্ষা করুন: prompt, final response, inference messages, tool name, arguments ও result documented attribute বা correlated event body-তে আছে কি না যাচাই করুন।
5. Correlation যাচাই করুন: conversation-এর span-এ একই সঠিক session.id, একটি turn-এ একই trace_id এবং tool request-result জোড়ায় matching call ID আছে কি না দেখুন।
6. Data source মিলিয়ে নিন: split telemetry হলে span এবং correlated message content—দুটিই evaluation configuration-এর নির্বাচিত log group থেকে পাওয়া যাচ্ছে কি না নিশ্চিত করুন।

Debugging শুরু করুন একটি turn দিয়ে: একটি agent span, একটি inference span এবং tool ব্যবহৃত হলে একটি tool span। প্রথমে scope ও role classification, তারপর extracted content, শেষে session correlation পরীক্ষা করলে transport, classification এবং field-extraction failure আলাদা করে ধরা যায়।

আরও পড়ুন:

• YouTube Custom Feed-এ আটটি prompt—creator discovery-র নতুন পরীক্ষা এখন সীমিত
• Gemini Enterprise-এ pay-as-you-go: agent খরচে hard cap-ও এল