AgentCore 可觀測性入門

Amazon Bedrock Amazon Bedrock AgentCore 可觀測性可協助您追蹤、偵錯和監控生產環境中的代理程式效能。本指南可協助您在代理程式應用程式中實作可觀測性功能。

先決條件

開始之前，請確定您有：

Amazon Bedrock AgentCore 可觀測性提供兩種方式來設定監控以符合不同的基礎設施需求：

做為每個 AWS 帳戶的一次性設定，第一次使用者需要在 Amazon CloudWatch 上啟用交易搜尋。有兩種方式可以透過 API 和 CloudWatch 主控台執行此操作。

步驟 1：在 CloudWatch 上啟用交易搜尋

啟用 Transaction Search 後，需等待約十分鐘，範圍才可用於搜尋和分析。選擇下列其中一個選項：

選項 1：使用 API 啟用交易搜尋

使用 API 啟用交易搜尋

選項 2：在 CloudWatch 主控台中啟用交易搜尋

在 CloudWatch 主控台中啟用交易搜尋

現在讓我們繼續探索兩種設定可觀測性的方式。

步驟 2：啟用 Amazon Bedrock AgentCore 執行期託管代理程式的可觀測性

Amazon Bedrock AgentCore 執行期託管代理程式會直接在 Amazon Bedrock AgentCore 環境中部署和執行，以最少的組態提供自動檢測。當您使用 AgentCore CLI 部署代理程式時，執行時間會自動使用 OpenTelemetry 檢測您的代理程式，不需要額外的 OTEL 程式庫或組態。

如需完整範例，請參閱此筆記本

建立您的代理程式專案

使用 AgentCore CLI 建立新專案。這會設定您的專案資料夾、虛擬環境和相依性：

npm install -g @aws/agentcore
agentcore create --name StrandsClaudeGettingStarted

在專案的代理程式目錄中，將預設代理程式程式碼取代為您自己的代理程式邏輯。以下是使用 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")
    response = agent(user_input)
    return response.message['content'][0]['text']

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

部署和叫用您的代理程式

將代理程式部署到 AgentCore 執行期。AgentCore CLI 會處理封裝、部署和自動 OTEL 檢測：

cd StrandsClaudeGettingStarted
agentcore deploy

部署之後，您的代理程式會在 AgentCore 執行期上執行，並使用 OpenTelemetry 自動檢測。叫用您的代理程式，並在 Amazon CloudWatch 的 GenAI 可觀測性儀表板上檢視追蹤、工作階段和指標：

agentcore invoke

或者，您可以使用 AWS SDK 以程式設計方式調用代理程式：

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()))

步驟 3：啟用非 Amazon Bedrock AgentCore 託管代理程式的可觀測性

對於在 Amazon Bedrock AgentCore 執行時間之外執行的代理程式，您可以為部署在自有基礎設施上的代理程式提供相同的監控功能。無論您的代理程式在何處執行，這都允許一致的可觀測性。使用下列步驟來設定觀察代理程式所需的環境變數。

如需完整範例，請參閱 GitHub 網站上的 Amazon EKS 上的客服人員範例。

設定 AWS 環境變數

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>

設定 CloudWatch 記錄

在 Amazon CloudWatch 中為您的代理程式建立日誌群組和日誌串流，可用於設定下列環境變數。

設定 OpenTelemetry 環境變數

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

以唯一名稱取代 <YOUR-AGENT-NAME>，以在 GenAI 可觀測性儀表板和日誌中識別此代理程式。

在本機建立代理程式

# 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)

使用自動檢測命令執行您的代理程式

在您的 requirements.txt aws-opentelemetry-distro中使用 ，opentelemetry-instrument命令將：

使用下列命令透過自動檢測來執行您的代理程式：

opentelemetry-instrument python agent.py

如果您在 AWS Lambda 上託管代理程式，請使用 AWS Distro AWS for OpenTelemetry 網站上的 Lambda Layer for OpenTelemetry。將 layer 新增至函數，然後將AWS_LAMBDA_EXEC_WRAPPER環境變數設定為 /opt/otel-instrument。然後， layer 會自動檢測您的函數。使用此方法，您不需要新增aws-opentelemetry-distro套件或執行先前所述的opentelemetry-instrument命令。

您現在可以使用您在環境變數中設定的 YOUR-AGENT-NAME 值，在 Amazon CloudWatch 的 GenAI 可觀測性儀表板上檢視追蹤、工作階段和指標。

若要關聯多個代理程式執行的追蹤，您可以使用 OpenTelemetry 包包將工作階段 ID 與您的遙測資料建立關聯：

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

步驟 4：在 Amazon CloudWatch 上使用 GenAI 可觀測性觀察您的代理程式

實作可觀測性之後，您可以在 CloudWatch 中檢視收集的資料：

觀察您的代理程式

檢視 CloudWatch 中的日誌

在 CloudWatch 中檢視日誌

檢視追蹤和範圍

檢視追蹤和範圍

檢視 指標

檢視指標

最佳實務