# AgentCore 관찰성 시작하기
Amazon Bedrock Amazon Bedrock AgentCore 관찰성을 사용하면 프로덕션 환경에서 에이전트 성능을 추적, 디버깅 및 모니터링할 수 있습니다. 이 가이드는 에이전트 애플리케이션에서 관찰성 기능을 구현하는 데 도움이 됩니다.
**Topics**
+ [사전 조건](#prerequisites)
+ [1단계: CloudWatch에서 트랜잭션 검색 활성화](#enabling-transaction-search)
+ [2단계: Amazon Bedrock AgentCore 런타임 호스팅 에이전트에 대한 관찰성 활성화](#enabling-observability-runtime-hosted)
+ [3단계: 비 Amazon Bedrock AgentCore 호스팅 에이전트에 대한 관찰성 활성화](#enabling-observability-non-runtime-hosted)
+ [4단계: Amazon CloudWatch에서 GenAI 관찰성을 사용하여 에이전트 관찰](#agentcore-observability-genai-cloudwatch)
+ [모범 사례](#best-practices)
## 사전 조건
시작하기 전에 다음이 있는지 확인합니다.
+ ** AWS 사용하려는 파운데이션 모델에 대해 모델 액세스가 활성화된 자격 증명이 구성된 계정**(`aws configure`).
+ **Python 3.10 이상** 설치됨
+ Amazon CloudWatch에서 **트랜잭션 검색을 활성화합니다**. 최초 사용자는 한 번만 [CloudWatch 트랜잭션 검색을](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Enable-TransactionSearch.html) 활성화하여 Bedrock Amazon Bedrock AgentCore 스팬 및 트레이스를 확인해야 합니다.
+ **(비 런타임 에이전트만 해당) OpenTelemetry 라이브러리 추가 -** requirements.txt 파일에 `aws-opentelemetry-distro` (ADOT)를 포함합니다. AWS Lambda에서 에이전트를 호스팅하는 경우 AWS Distro [AWS for OpenTelemetry 웹 사이트에서 Lambda Layer](https://aws-otel.github.io/docs/getting-started/lambda) for OpenTelemetry를 대신 사용합니다.
+ **(런타임이 아닌 에이전트만 해당)** 프레임워크가 트레이스(예: `strands-agents[otel]` 패키지)를 내보내도록 구성되어 있는지 확인합니다. 에이전트 프레임워크의 자동 계측기(예: `opentelemetry-instrumentation-langchain` )를 포함해야 하는 경우가 있습니다.
Amazon Bedrock AgentCore 관찰성은 다양한 인프라 요구 사항에 맞게 모니터링을 구성하는 두 가지 방법을 제공합니다.
1. Amazon Bedrock AgentCore 런타임 호스팅 에이전트
1. 비 런타임 호스팅 에이전트
AWS 계정당 일회성 설정으로 처음 사용하는 사용자는 Amazon CloudWatch에서 트랜잭션 검색을 활성화해야 합니다. API와 CloudWatch 콘솔을 통해 이를 수행하는 두 가지 방법이 있습니다.
## 1단계: CloudWatch에서 트랜잭션 검색 활성화
트랜잭션 검색을 활성화한 후 검색 및 분석에 스팬을 사용할 수 있기까지 10분 정도 소요될 수 있습니다. 아래 옵션 중 하나를 선택합니다.
### 옵션 1: API를 사용하여 트랜잭션 검색 활성화
**API를 사용하여 트랜잭션 검색을 활성화하려면**
1. AWS CLI를 사용하여 CloudWatch Logs에서 스팬을 수집할 수 있는 액세스 권한을 부여하는 정책을 생성합니다.
CLI AWS 명령을 로 포맷하는 방법에 대한 예제가 아래에 나와 있습니다`PutResourcePolicy`.
```
aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:xray:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}'
```
1. 트레이스 세그먼트의 대상을 구성합니다.
CLI AWS 명령을 로 포맷하는 방법에 대한 예제가 아래에 나와 있습니다`UpdateTraceSegmentDestination`.
```
aws xray update-trace-segment-destination --destination CloudWatchLogs
```
1. **선택 사항** 인덱싱할 스팬의 양을 구성합니다.
를 사용하여 원하는 샘플링 백분율을 구성합니다`UpdateIndexingRule`.
```
aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}'
```
### 옵션 2: CloudWatch 콘솔에서 트랜잭션 검색 활성화
**CloudWatch 콘솔에서 트랜잭션 검색을 활성화하려면**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 설정 아래의 탐색 창에서 **설정을** **** 선택합니다.
1. **계정을** 선택하고 **X-Ray 추적** 탭을 선택합니다.
1. **트랜잭션 검색** 섹션에서 **설정 보기를** 선택합니다.
1. 열리는 페이지에서 **편집**을 선택합니다.
1. **Enable Transaction Search**를 선택합니다.
1. **X-Ray 사용자에 대해**를 선택하고 인덱싱할 트레이스의 백분율을 입력합니다. 추적의 1%를 무료로 인덱싱하고 필요에 따라 나중에이 비율을 조정할 수 있습니다.
1. **저장**을 선택합니다. 추적을 전송하기 전에 **OpenTelemetry 범위 수집**이 **활성화됨**으로 표시될 때까지 기다립니다.
이제 관찰성을 구성하는 두 가지 방법을 살펴보겠습니다.
## 2단계: Amazon Bedrock AgentCore 런타임 호스팅 에이전트에 대한 관찰성 활성화
Amazon Bedrock AgentCore 런타임 호스팅 에이전트는 Amazon Bedrock AgentCore 환경 내에서 직접 배포 및 실행되므로 최소한의 구성으로 자동 계측이 가능합니다. AgentCore CLI를 사용하여 에이전트를 배포하면 런타임이 OpenTelemetry로 에이전트를 자동으로 계측하므로 추가 OTEL 라이브러리 또는 구성이 필요하지 않습니다.
전체 예제는이 [노트북](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/06-AgentCore-observability/01-Agentcore-runtime-hosted/Strands%20Agents/runtime_with_strands_and_bedrock_models.ipynb)을 참조하세요.
### 에이전트 프로젝트 생성
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 샘플을](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-eks) 참조하세요.
### AWS 환경 변수 구성
```
export AWS_ACCOUNT_ID=
export AWS_DEFAULT_REGION=
export AWS_REGION=
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_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=,x-aws-log-stream=,x-aws-metric-namespace=
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=,x-aws-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= # 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
```
{{}}을 고유한 이름으로 바꾸어 GenAI 관찰성 대시보드 및 로그에서이 에이전트를 식별합니다.
**참고**
자체 로그 그룹에 범위를 전달`OTEL_EXPORTER_OTLP_TRACES_HEADERS`하도록를 설정한 경우 Amazon CloudWatch Logs 리소스 정책도 추가해야 합니다. 정책은 X-Ray(`xray.amazonaws.com`)가 해당 로그 그룹에서 `logs:PutLogEvents`를 호출하도록 허용해야 합니다. [API를 사용하여 트랜잭션 검색 활성화](#enable-transaction-search-api)에 표시된 것과 동일한 정책을에서 로그 그룹의 ARN과 함께 사용합니다`Resource`. 이 정책이 없으면 X-Ray는 로그 그룹에 범위를 전달할 수 없습니다.
### 로컬에서 에이전트 생성
```
# 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` 명령은 다음을 수행합니다.
+ 환경 변수에서 OTEL 구성 로드
+ Strands, Amazon Bedrock 호출, 에이전트 도구 및 데이터베이스, 에이전트가 수행한 기타 요청을 자동으로 계측합니다.
+ CloudWatch로 추적 전송
+ GenAI 관찰성 대시보드에서 에이전트의 의사 결정 프로세스를 시각화할 수 있습니다.
다음 명령을 사용하여 자동 계측으로 에이전트를 실행합니다.
```
opentelemetry-instrument python agent.py
```
AWS Lambda에서 에이전트를 호스팅하는 경우 AWS Distro [AWS for OpenTelemetry 웹 사이트에서 Lambda Layer](https://aws-otel.github.io/docs/getting-started/lambda) for OpenTelemetry를 사용합니다. 함수에 계층을 추가한 다음 `AWS_LAMBDA_EXEC_WRAPPER` 환경 변수를 로 설정합니다`/opt/otel-instrument`. 그러면 계층이 함수를 자동 계측합니다. 이 접근 방식을 사용하면 `aws-opentelemetry-distro` 패키지를 추가하거나 앞서 설명한 `opentelemetry-instrument` 명령을 실행할 필요가 없습니다.
**에이전트 관찰성에 대해 ADOT Collector가 지원되지 않음**
ADOT Collector는 에이전트 관찰성에 대해 지원되지 않습니다. AgentCore 런타임 외부에서 호스팅되는 에이전트에서 원격 측정을 보내려면 ADOT SDK 또는 OpenTelemetry용 AWS Lambda 계층을 사용해야 합니다.
이제 Amazon CloudWatch의 GenAI 관찰성 대시보드에서 [환경 변수](#configure-opentelemetry-environment-variables)에 구성한 **YOUR-AGENT-NAME** 값을 사용하여 트레이스, 세션 및 지표를 볼 수 있습니다.
여러 에이전트 실행에서 트레이스를 상호 연관시키려면 OpenTelemetry 도우미를 사용하여 세션 ID를 원격 측정 데이터와 연결할 수 있습니다.
```
from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)
```
## 4단계: Amazon CloudWatch에서 GenAI 관찰성을 사용하여 에이전트 관찰
관찰성을 구현한 후 CloudWatch에서 수집된 데이터를 볼 수 있습니다.
### 에이전트 관찰
1. [CloudWatch 콘솔에서 GenAI 관찰성](https://console.aws.amazon.com/cloudwatch/home#gen-ai-observability) 열기
1. 대시보드의 Bedrock Amazon Bedrock AgentCore에서 모델 호출 및 에이전트와 관련된 데이터를 볼 수 있습니다.
1. Bedrock Agentcore 탭에서 에이전트 보기, 세션 보기 및 트레이스 보기를 볼 수 있습니다.
1. 에이전트 보기에는 런타임이 아닌에 있는 모든 에이전트가 나열됩니다. 에이전트를 선택하고 런타임 지표, 세션 및 에이전트별 추적과 같은 추가 세부 정보를 볼 수도 있습니다.
1. **세션 보기** 탭에서 에이전트와 연결된 모든 세션을 탐색할 수 있습니다.
1. **추적 보기** 탭에서 에이전트에 대한 추적 및 범위 정보를 살펴볼 수 있습니다. 또한 트레이스를 선택하여 트레이스 궤적과 타임라인을 탐색합니다.
### CloudWatch에서 로그 보기
**CloudWatch에서 로그를 보려면**
1. [CloudWatch 콘솔](https://console.aws.amazon.com/cloudwatch/) 열기
1. 왼쪽 탐색 창에서 **로그를 확장**하고 **로그 그룹을** 선택합니다.
1. 에이전트의 로그 그룹을 검색합니다.
+ 표준 로그(stdout/stderr) 위치: `/aws/bedrock-agentcore/runtimes/-/[runtime-logs] `
+ OTEL 구조화된 로그: `/aws/bedrock-agentcore/runtimes/-/runtime-logs`
### 트레이스 및 스팬 보기
**트레이스 및 스팬을 보려면**
1. [CloudWatch 콘솔](https://console.aws.amazon.com/cloudwatch/) 열기
1. 왼쪽 탐색에서 **트랜잭션 검색을** 선택합니다.
1. 위치: 에이전트의 `spans` 로그 그룹(`/aws/bedrock-agentcore/runtimes/-`)에 있는 로그 스트림 또는 공유 스팬 대상을 사용하는 에이전트에 대한 로그 그룹의 `aws/spans` 로그 `default` 스트림
1. 서비스 이름 또는 기타 기준을 기준으로 필터링
1. 세부 실행 그래프를 보려면 추적을 선택합니다.
### 지표 보기
**지표를 보려면**
1. [CloudWatch 콘솔](https://console.aws.amazon.com/cloudwatch/) 열기
1. 왼쪽 탐색 창에서 **지표**를 선택합니다.
1. `bedrock-agentcore` 네임스페이스 찾아보기
1. 사용 가능한 지표 탐색
## 모범 사례
1. **간단한 시작 후 확장** - Amazon Bedrock AgentCore에서 제공하는 기본 관찰성은 모델 호출, 토큰 사용 및 도구 실행을 포함하여 가장 중요한 지표를 자동으로 캡처합니다.
1. **개발 단계를 위한 구성** - 현재 개발 단계에 맞게 관찰성 구성을 조정하고 점진적으로 조정합니다.
1. **일관된 이름 지정 사용** - 처음부터 서비스, 범위 및 속성에 대한 이름 지정 규칙 설정
1. **민감한 데이터 필터링** - 관찰성 속성 및 페이로드에서 민감한 데이터를 필터링하여 기밀 정보의 노출을 방지합니다.
1. **알림 설정** - 사용자에게 영향을 미치기 전에 잠재적 문제를 알리도록 CloudWatch 경보 구성