AI ajanını her çatıyla ölçmek: AgentCore’da telemetri şartı

Kendi ajan çatınızı Amazon Bedrock AgentCore Evaluations ile ölçebilirsiniz; ancak bunun için yalnızca geçerli OpenTelemetry verisi göndermek yeterli değildir. İzlerin tanınan bir scope adı taşıması, değerlendirilecek span’lerin sınıflandırılması, konuşmanın session.id ile birleştirilmesi ve gerekli mesaj içeriğinin belgelenen alanlarda bulunması gerekir.

Bu koşullardan biri eksik olduğunda telemetri CloudWatch’a ulaşsa bile değerlendirme eksik kalabilir veya sonuç üretmeyebilir. Dolayısıyla uyumluluk testi, “iz geldi mi?” sorusuyla bitmemeli; AgentCore’un izi sınıflandırıp konuşmaya dönüştürebildiği ve seçilen evaluator’a anlamlı içerik verebildiği doğrulanmalıdır.

Dört koşullu telemetri sözleşmesi

İlk karar, OpenTelemetry GenAI veya OpenInference sözleşmelerinden hangisini uygulayacağınızdır. AWS’nin genel çatı desteği belgesi, AgentCore Evaluations’ın sözleşmeyi span üzerindeki scope.name değerinden seçtiğini; genel yol için opentelemetry.instrumentation.* ve openinference.instrumentation.* öneklerini tanıdığını belirtiyor.

• Scope: Özel enstrümantasyon adını seçilen sözleşmenin tanınan öneki altında oluşturun.
• Span sınıfı: OpenTelemetry span’lerinde gen_ai.operation.name veya desteklenen yedek sınıflandırma alanını; OpenInference span’lerinde openinference.span.kind alanını kullanın.
• Oturum: Aynı konuşmanın dönüşlerini ortak session.id altında tutun. Her kullanıcı dönüşü ayrı bir trace_id taşıyabilir.
• İçerik: Kullanıcı girdisini, nihai ajan yanıtını, model mesajlarını ve araç verilerini belgelenen span niteliklerine veya ilişkili event kayıtlarına yerleştirin.

OpenTelemetry yolunda invoke_agent üst düzey ajan dönüşünü, chat model çıkarımını, execute_tool ise araç çağrısını işaretler. OpenInference karşılıkları üst dönüş için AGENT veya CHAIN, çıkarım için LLM ve araç için TOOL değerleridir. Tanınan sınıflandırma niteliği bulunmayan bir span değerlendirme girdisine alınmaz.

HTTP istemcileri, web çatıları, MCP ve botocore gibi altyapı enstrümantasyonlarının bazı scope’ları doğru önekle başlasa da genel destek dışında tutulur. Bu ayrım, altyapı span’lerinin yanlışlıkla ajan, model veya araç işlemi sayılmasını önler.

Yanlış scope neden geçerli izi görünmez kılar?

Koşullu bir örnekte özel kütüphanenizin mycompany.agent.tracing scope’u altında eksiksiz gen_ai.operation.name ve mesaj alanları ürettiğini düşünün. Span biçimsel olarak OpenTelemetry ile uyumlu olsa da scope adı genel destek öneklerinden biriyle başlamadığı için AgentCore’un genel okuma yoluna girmez. opentelemetry.instrumentation.mycompany_agent gibi tanınan önek altındaki bir ad ise OpenTelemetry sözleşmesini seçtirir.

Kontrolü gerçek bir kullanıcı dönüşü üzerinden yapın. Önce scope.name değerini inceleyin; ardından üst span’de invoke_agent veya AGENT/CHAIN, model çağrısında chat veya LLM, araç çağrısında execute_tool veya TOOL sınıfını arayın. Yalnızca alt model span’lerinin görünmesi, üst düzey kullanıcı girdisi ile nihai ajan yanıtının eksiksiz kurulacağını garanti etmez.

Scope adını düzeltmek de tek başına yeterli değildir. OpenTelemetry için gen_ai.operation.name yoksa üst dönüşte traceloop.span.kind=workflow, araçta traceloop.span.kind=tool ve çıkarımda llm.request.type=chat desteklenen yedeklerdir. Özel ve belgelenmemiş bir span türü değeri kullanmak, hizmetin rolü tahmin edeceği anlamına gelmez.

Session.id ile mesaj içeriğini ayrı doğrulayın

AWS’nin 26 Ağustos 2026 tarihli uygulama yazısı, AgentCore Evaluations’ın oturumu session.id ile grupladığını ve oturum içindeki her trace_id değerini bir kullanıcı dönüşü olarak ele aldığını açıklıyor. Yazı ayrıca Strands Agents, LangGraph, OpenAI Agents SDK, LlamaIndex, Google ADK ve Claude Agent SDK dışındaki çatıların da tanınan OpenTelemetry veya OpenInference sözleşmesini uygulayarak genel yoldan değerlendirilebildiğini gösteriyor.

Özel ortamda, çağrıda kullandığınız oturum kimliği ile span üzerindeki attributes.session.id değerini karşılaştırın. Çok dönüşlü bir konuşmada her istekte yeni kimlik üretmek konuşmayı parçalar; farklı kullanıcılar için aynı kimliği kullanmak ise bağımsız konuşmaları birleştirir. AgentCore Runtime üzerinde ADOT bu niteliği otomatik ekleyebilir, fakat dışarıdan gönderilen özel telemetride alanın gerçekten bulunduğu ayrıca denetlenmelidir.

Ardından içerik alanlarını kontrol edin. OpenTelemetry üst dönüş girdisini önce event kaydındaki body.input, sonra gen_ai.task.input üzerinden; yanıtı body.output, ardından gen_ai.task.output üzerinden okur. Model mesajları body.input.messages ve body.output.messages ya da gen_ai.input.messages ve gen_ai.output.messages alanlarından alınabilir.

OpenInference yolunda üst dönüş için input.value ve output.value, model geçmişi için llm.input_messages.* ve llm.output_messages.* alanları kullanılır. Araç span’lerinde input.value argümanları, output.value sonucu taşır. AgentCore özel çatı veri modelini ayrıştırmak yerine çıkarılan değerleri metne dönüştürdüğünden, mesajları özel bir zarf içine gömmek evaluator’a temiz içerik yerine serileştirilmiş zarfı verebilir.

On-demand değerlendirmeyi çalıştırma

Önce sabit bir test girdisiyle ajanı çağırın ve kullanılan session ID’yi kaydedin. Kayıtların CloudWatch’a ulaşmasını bekledikten sonra aynı oturuma ait span ve ilişkili event kayıtlarını alın. Yalnızca span kayıtlarını toplamak, mesaj içeriğinin ayrı event kayıtlarında bulunduğu telemetri düzenlerinde yetersiz kalabilir.

1. Ajan çağrısını çalıştırın; test girdisini ve session ID’yi kaydedin.
2. CloudWatch sorgusunda scope.name ile attributes.session.id alanlarını doğrulayın.
3. Üst ajan, model ve varsa araç span’lerini ilişkili event kayıtlarıyla birlikte toplayın.
4. Builtin.Helpfulness gibi uygun bir yerleşik evaluator veya özel evaluator seçin.
5. AgentCore istemcisiyle session ID üzerinden çalıştırın ya da Evaluate API’ye evaluationInput.sessionSpans verin.
6. Başarılı ve hatalı sonuçları ayırarak value, label ve explanation alanlarını inceleyin.

On-demand değerlendirme kılavuzu, AgentCore istemcisinin belirli bir session ID için değerlendirme çalıştırabildiğini; doğrudan Evaluate API kullanıldığında CloudWatch’tan indirilen kayıtların sessionSpans olarak verilmesi gerektiğini gösteriyor. Trace düzeyinde hedefi evaluationTarget.traceIds, araç çağrısı düzeyinde ise evaluationTarget.spanIds ile daraltabilirsiniz.

Hata ayıklama sırası ve geçiş ölçütü

Hata ayıklamaya taşıma katmanından başlayıp orada durmayın. En kısa sıra, kaydın CloudWatch’ta bulunduğunu gördükten sonra scope önekini, span sınıfını, session.id eşleşmesini ve içerik alanlarını bu sırayla incelemektir. Böylece “iz mevcut” durumunu “iz değerlendirilebilir” sonucuyla karıştırmazsınız.

• Scope, genel desteğin tanıdığı iki önekten biriyle başlıyor ve dışlanan altyapı scope’larından biri değil.
• Değerlendirilecek her span ajan dönüşü, model çıkarımı veya araç çağrısı olarak sınıflandırılabiliyor.
• Bir kullanıcı dönüşünün span’leri aynı trace_id, konuşmanın dönüşleri aynı session.id altında birleşiyor.
• Üst dönüşte kullanıcı girdisi ile nihai ajan yanıtı boş değil.
• Model mesajları ile araç adı, argümanları ve sonucu belgelenen alanlardan çıkarılabiliyor.
• On-demand çağrı, beklenen oturum, trace veya span hedefi için başarılı bir değerlendirme sonucu döndürüyor.

Bu denetimlerin tamamı geçtiğinde özel çatı yalnızca standart biçimde telemetri göndermiş olmaz. AgentCore Evaluations’ın sınıflandırabileceği, tek bir konuşma halinde kurabileceği ve seçilen evaluator ile puanlayabileceği veri üretmiş olur.