Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Memulai dengan AgentCore Observability

Amazon Bedrock AgentCore Observability membantu Anda melacak, men-debug, dan memantau kinerja agen di lingkungan produksi. Panduan ini membantu Anda menerapkan fitur observabilitas dalam aplikasi agen Anda.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Amazon Bedrock AgentCore Observability menawarkan dua cara untuk mengonfigurasi pemantauan agar sesuai dengan kebutuhan infrastruktur yang berbeda:

Sebagai pengaturan satu kali per AWS akun, pengguna pertama kali harus mengaktifkan Pencarian Transaksi di Amazon CloudWatch. Ada dua cara untuk melakukan ini, melalui API dan melalui Kon CloudWatch sol.

Langkah 1: Aktifkan pencarian transaksi pada CloudWatch

Setelah Anda mengaktifkan Pencarian Transaksi, diperlukan waktu sepuluh menit agar rentang tersedia untuk pencarian dan analisis. Pilih salah satu opsi di bawah ini:

Opsi 1: Aktifkan pencarian transaksi menggunakan API

Untuk mengaktifkan pencarian transaksi menggunakan API

Opsi 2: Aktifkan pencarian transaksi di CloudWatch konsol

Untuk mengaktifkan pencarian transaksi di CloudWatch konsol

Sekarang mari kita lanjutkan untuk mengeksplorasi dua cara untuk mengkonfigurasi observabilitas.

Langkah 2: Aktifkan pengamatan untuk agen yang dihosting Amazon Bedrock AgentCore Runtime

Agen Amazon Bed AgentCore Runtime-hosted rock dikerahkan dan dieksekusi langsung di AgentCore lingkungan Amazon Bedrock, menyediakan instrumentasi otomatis dengan konfigurasi minimal. Saat Anda menyebarkan agen menggunakan AgentCore CLI, runtime akan secara otomatis menginstrumentasi agen Anda dengan OpenTelemetry — tidak diperlukan pustaka atau konfigurasi OTEL tambahan.

Untuk contoh lengkap, lihat Sampel AgentCore Pengamatan pada GitHub

Buat proyek agen Anda

Buat proyek baru menggunakan AgentCore CLI. Ini mengatur folder proyek Anda, lingkungan virtual, dan dependensi:

npm install -g @aws/agentcore
agentcore create \
  --project-name StrandsObservability \
  --name StrandsClaudeGettingStarted \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none
cd StrandsObservability/app/StrandsClaudeGettingStarted
uv add strands-agents-tools
cd ../..

Di direktori agen proyek, ganti kode agen default dengan logika agen Anda sendiri. Berikut ini adalah contoh menggunakan Strands Agents SDK:

## app/StrandsClaudeGettingStarted/main.py
from strands import Agent, tool
from strands_tools import calculator
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

@tool
def weather():
    """Get weather"""
    return "sunny"

model = BedrockModel(
    model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
)
agent = Agent(
    model=model,
    tools=[calculator, weather],
    system_prompt="You're a helpful assistant. You can do simple math calculation, and tell the weather."
)

@app.entrypoint
def strands_agent_bedrock(payload):
    """Invoke the agent with a payload"""
    user_input = payload.get("prompt")
    if not isinstance(user_input, str) or not user_input:
        return "Error: 'prompt' must be a non-empty string"
    response = agent(user_input)
    return response.message['content'][0]['text']

if __name__ == "__main__":
    app.run()

Menyebarkan dan memanggil agen Anda

Menyebarkan agen ke AgentCore Runtime. AgentCore CLI menangani pengemasan, penyebaran, dan instrumentasi OTEL otomatis:

agentcore deploy

Setelah penerapan, agen Anda berjalan pada AgentCore Runtime dan secara otomatis diinstrumentasi menggunakan OpenTelemetry. Panggil agen Anda dan lihat jejak, sesi, dan metrik di dasbor Pengamatan GenAI di Amazon: CloudWatch

agentcore invoke

Atau, Anda dapat memanggil agen Anda secara terprogram menggunakan SDK: AWS

import boto3, json

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn="YOUR_AGENT_RUNTIME_ARN",
    runtimeSessionId="my-observability-session-001",
    payload=json.dumps({"prompt": "What is 2 + 2?"}),
    qualifier="DEFAULT"
)

print(json.loads(response['response'].read()))

Langkah 3: Aktifkan observabilitas untuk agen non-Amazon Bedrock AgentCore-hosted

Untuk agen yang berjalan di luar AgentCore runtime Amazon Bedrock, Anda dapat memberikan kemampuan pemantauan yang sama untuk agen yang digunakan pada infrastruktur Anda sendiri. Hal ini memungkinkan pengamatan yang konsisten terlepas dari mana agen Anda berjalan. Gunakan langkah-langkah berikut untuk mengonfigurasi variabel lingkungan yang diperlukan untuk mengamati agen Anda.

Untuk contoh lengkapnya, lihat sampel Agen di Amazon EKS di GitHub situs web.

Konfigurasi AWS variabel lingkungan

export AWS_ACCOUNT_ID=<account id>
export AWS_DEFAULT_REGION=<default region>
export AWS_REGION=<region>
export AWS_ACCESS_KEY_ID=<access key id>
export AWS_SECRET_ACCESS_KEY=<secret key>

Konfigurasikan pen CloudWatch catatan

Buat grup log dan aliran log untuk agen Anda di Amazon CloudWatch yang dapat Anda gunakan untuk mengonfigurasi variabel lingkungan di bawah ini.

Konfigur OpenTelemetry asikan variabel lingkungan

export AGENT_OBSERVABILITY_ENABLED=true # Activates the ADOT pipeline
export OTEL_PYTHON_DISTRO=aws_distro # Uses AWS Distro for OpenTelemetry
export OTEL_PYTHON_CONFIGURATOR=aws_configurator # Sets AWS configurator for ADOT SDK
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # Configures export protocol
export  OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-LOG-STREAM>,x-aws-metric-namespace=<YOUR-NAMESPACE>
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-TRACES-LOG-STREAM>
# (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR-AGENT-NAME> # Identifies your agent in observability data
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
export OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
export OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

Ganti <YOUR-AGENT-NAME> dengan nama unik untuk mengidentifikasi agen ini di dasbor dan log Pengamatan GenAI.

Buat agen secara lokal

# Create agent.py -  Strands agent that is a weather assistant
from strands import Agent
from strands_tools import http_request

# Define a weather-focused system prompt
WEATHER_SYSTEM_PROMPT = """You are a weather assistant with HTTP capabilities. You can:

1. Make HTTP requests to the National Weather Service API
2. Process and display weather forecast data
3. Provide weather information for locations in the United States

When retrieving weather information:
1. First get the coordinates or grid information using https://api.weather.gov/points/{latitude},{longitude} or https://api.weather.gov/points/{zipcode}
2. Then use the returned forecast URL to get the actual forecast

When displaying responses:
- Format weather data in a human-readable way
- Highlight important information like temperature, precipitation, and alerts
- Handle errors appropriately
- Convert technical terms to user-friendly language

Always explain the weather conditions clearly and provide context for the forecast.
"""

# Create an agent with HTTP capabilities
weather_agent = Agent(
    system_prompt=WEATHER_SYSTEM_PROMPT,
    tools=[http_request],  # Explicitly enable http_request tool
)

response = weather_agent("What's the weather like in Seattle?")
print(response)

Jalankan agen Anda dengan perintah instrumentasi otomatis

Dengan aws-opentelemetry-distro di requirements.txt Anda, opentelemetry-instrument perintah akan:

Gunakan perintah berikut untuk menjalankan agen Anda dengan instrumentasi otomatis:

opentelemetry-instrument python agent.py

Jika Anda meng-host agen Anda di AWS Lambda, gunakan AWS Lambda Layer untuk OpenTelemetry di AWS Distro for situs web. OpenTelemetry Tambahkan layer ke fungsi Anda, dan kemudian atur variabel AWS_LAMBDA_EXEC_WRAPPER lingkungan ke/opt/otel-instrument. Lapisan kemudian secara otomatis menginstrumentasikan fungsi Anda. Dengan pendekatan ini, Anda tidak perlu menambahkan aws-opentelemetry-distro paket atau menjalankan opentelemetry-instrument perintah yang dijelaskan sebelumnya.

Anda sekarang dapat melihat jejak, sesi, dan metrik Anda di Dasbor Pengamatan GenAI di Amazon CloudWatch dengan nilai YOUR-AGENT-NAME yang Anda konfigurasikan dalam variabel lingkungan Anda.

Untuk menghubungkan pelacakan di beberapa operasi agen, Anda dapat mengaitkan ID sesi dengan data telemetri menggunakan OpenTelemetry bagasi:

from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)

Langkah 4: Amati agen Anda dengan pengamatan GenAI di Amazon CloudWatch

Setelah menerapkan observabilitas, Anda dapat melihat data yang dikumpulkan di: CloudWatch

Amati agen Anda

Lihat log masuk CloudWatch

Untuk melihat log masuk CloudWatch

Melihat jejak dan rentang

Untuk melihat jejak dan rentang

Melihat metrik

Untuk melihat metrik

Praktik terbaik