‏AgentCore Observability برای ایجنت‌های بیرون از AWS

وقتی یه ایجنت AI رو با فریم‌ورک‌هایی مثل Strands Agents یا LangGraph می‌سازی و بیرون از AWS اجراش می‌کنی، داشبورد Amazon Bedrock AgentCore Observability — یعنی همون جایی که تریس و متریک ایجنت‌ها رو یکجا نشون می‌ده — به‌صورت پیش‌فرض هیچی ازش نمی‌بینه، چون فقط ایجنت‌های روی AgentCore runtime رو ساپورت می‌کنه. تو این پست تیم AWS نشون می‌ده چطور همین مسیر رو برای سرور آن‌پرمیس یا کلاود دیگه باز کنی.

راه‌حل سه تیکه داره. اول پکیج aws-opentelemetry-distro (همون ADOT) که کنار خود اپلیکیشن اجرا می‌شه و با دستور opentelemetry-instrument هم boto3 و هم فریم‌ورک Strands رو خودکار instrument می‌کنه؛ یعنی لازم نیست دستی به کدت span اضافه کنی. دوم کلیدهای IAM که ADOT باهاشون درخواست‌های خروجی رو با SigV4 امضا می‌کنه. سوم یه سری متغیر محیطی OpenTelemetry که مقصد تله‌متری رو مشخص می‌کنن.

اون متغیرها چیزی شبیه اینان و مستقیم به اندپوینت OTLP خود CloudWatch وصل می‌شن:

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-external-agent,aws.log.group.names=/aws/bedrock-agentcore/runtimes/my-external-agent"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp

کلیدی‌ترین تیکه aws.log.group.names هست: همینه که به CloudWatch می‌گه داده رو زیر داشبورد GenAI ایندکس کنه، وگرنه تریس‌ها می‌افتن تو لاگ‌گروپ‌های معمولی و تو داشبورد ایجنت‌ها پیداشون نمی‌کنی.

تیم AWS این ستاپ رو روی دو محیط تست کرده: یه سرور آن‌پرمیس شبیه‌سازی‌شده و Google Cloud Shell که روی زیرساخت GCP بالا میاد. تو هر دو، ایجنت با مدل Claude Haiku دو سه دقیقه بعد از اجرا سشن‌ها، تریس‌ها، تأخیر و مصرف توکن رو تو همون داشبورد نشون داده، دقیقاً مثل ایجنت‌های داخل AgentCore runtime. پیش‌نیازش هم Python 3.10 به بالا (پیشنهادشون 3.12) و روشن‌بودن CloudWatch Transaction Search تو اکانته.

به گفتهٔ نویسنده‌ها بهتره تو پروداکشن سراغ اکسس‌کی بلندمدت نری و از IAM Roles Anywhere با گواهی X.509 کردنشیال موقت بگیری. یه هشدار عملی هم می‌دن: اگه کردنشیال درست نباشه ADOT بی‌صدا فیل می‌شه و هیچ اروری نمی‌بینی، پس اول با get-caller-identity تستش کن. service.name هم همون اسمیه که تو داشبورد می‌بینی، پس اسم محیط رو توش بیار.

نکات کلیدی:

• AgentCore Observability فقط ایجنت‌های روی AgentCore runtime رو خودکار پوشش می‌ده؛ بقیه ستاپ دستی می‌خوان.
• کل نصب یه pip install پکیج ADOT و Strands هست، به‌علاوهٔ چند متغیر محیطی OpenTelemetry.
• بدون aws.log.group.names، تریس‌ها به‌جای داشبورد GenAI تو لاگ‌های عادی CloudWatch می‌شینن.
• کاربر IAM به bedrock:InvokeModel، نوشتن تو CloudWatch Logs و اکشن‌های X-Ray نیاز داره.
• تست‌شده روی آن‌پرمیس و Google Cloud Shell؛ داده تو دو تا سه دقیقه می‌رسه.