AgentCore 관찰성 시작하기

Amazon Bedrock Amazon Bedrock AgentCore 관찰성을 사용하면 프로덕션 환경에서 에이전트 성능을 추적, 디버깅 및 모니터링할 수 있습니다. 이 가이드는 에이전트 애플리케이션에서 관찰성 기능을 구현하는 데 도움이 됩니다.

사전 조건

시작하기 전에 다음이 있는지 확인합니다.

Amazon Bedrock AgentCore 관찰성은 다양한 인프라 요구 사항에 맞게 모니터링을 구성하는 두 가지 방법을 제공합니다.

AWS 계정당 일회성 설정으로 처음 사용하는 사용자는 Amazon CloudWatch에서 트랜잭션 검색을 활성화해야 합니다. API와 CloudWatch 콘솔을 통해 이를 수행하는 두 가지 방법이 있습니다.

1단계: CloudWatch에서 트랜잭션 검색 활성화

트랜잭션 검색을 활성화한 후 검색 및 분석에 스팬을 사용할 수 있기까지 10분 정도 소요될 수 있습니다. 아래 옵션 중 하나를 선택합니다.

옵션 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 웹 사이트의 Agents on 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.txtaws-opentelemetry-distro의에서 opentelemetry-instrument 명령은 다음을 수행합니다.

다음 명령을 사용하여 자동 계측으로 에이전트를 실행합니다.

opentelemetry-instrument python agent.py

AWS Lambda에서 에이전트를 호스팅하는 경우 AWS Distro AWS for OpenTelemetry 웹 사이트에서 Lambda Layer for OpenTelemetry를 사용합니다. 함수에 계층을 추가한 다음 AWS_LAMBDA_EXEC_WRAPPER 환경 변수를 로 설정합니다/opt/otel-instrument. 그러면 계층이 함수를 자동 계측합니다. 이 접근 방식을 사용하면 aws-opentelemetry-distro 패키지를 추가하거나 앞서 설명한 opentelemetry-instrument 명령을 실행할 필요가 없습니다.

이제 Amazon CloudWatch의 GenAI 관찰성 대시보드에서 환경 변수에 구성한 YOUR-AGENT-NAME 값을 사용하여 트레이스, 세션 및 지표를 볼 수 있습니다.

여러 에이전트 실행에서 트레이스를 상호 연관시키려면 OpenTelemetry 도우미를 사용하여 세션 ID를 원격 측정 데이터와 연결할 수 있습니다.

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

4단계: Amazon CloudWatch에서 GenAI 관찰성을 사용하여 에이전트 관찰

관찰성을 구현한 후 CloudWatch에서 수집된 데이터를 볼 수 있습니다.

에이전트 관찰

CloudWatch에서 로그 보기

CloudWatch에서 로그를 보려면

트레이스 및 스팬 보기

트레이스 및 스팬을 보려면

지표 보기

지표를 보려면

모범 사례