# Strands Agents
이 페이지에서는 [Strands Agents](https://strandsagents.com/latest/) 에이전트를 계측하는 방법, 스팬을 식별하는 방법, 평가 필드를 추출하는 방법을 설명합니다.
**주제**
+ [에이전트 계측](#strands-instrument)
+ [스팬 식별 방법](#strands-span-identification)
+ [평가 필드 추출 방법](#strands-extraction)
+ [이벤트 레코드에서](#strands-extraction-event-records)
+ [인라인 스팬 이벤트에서](#strands-extraction-inline-events)
+ [이벤트 레코드가 있는 스팬의 예](#strands-examples-with)
+ [이벤트 레코드가 없는 스팬의 예](#strands-examples-without)
## 에이전트 계측
Strands Agents SDK에는 기본 제공 원격 측정이 포함되어 있으며 추가 계측 라이브러리가 필요하지 않습니다. 범위 이름 아래에 스팬 및 이벤트 레코드를 생성합니다`strands.telemetry.tracer`. AWS Distro for OpenTelemetry(ADOT)를 사용하여 Amazon Bedrock AgentCore 런타임에 배포하면 런타임은 `session.id` 속성을 주입하고 스팬 및 이벤트 레코드를 자동으로 내보냅니다.
**참고**
계측은 관찰성을 설정하는 한 단계입니다. 평가를 위해 원격 측정을 내보내려면 [관찰성 설정](supported-frameworks.md#supported-frameworks-setup)에서 전체 설정을 완료합니다.
## 스팬 식별 방법
Strands는 각 스팬에 `gen_ai.operation.name` 속성을 설정합니다. 평가 서비스는이 속성을 사용하여 범위를 분류합니다.
| 범위 유형 | 속성 식별 | 스팬 이름 예 |
| --- | --- | --- |
| 에이전트 호출 | `gen_ai.operation.name` = `invoke_agent` | `invoke_agent TravelAgent` |
| 도구 실행 | `gen_ai.operation.name` = `execute_tool` | `execute_tool search_flights` |
| Inference | `gen_ai.operation.name` = `chat` | `chat` |
## 평가 필드 추출 방법
대화 콘텐츠의 위치는 원격 측정이 수집된 방식에 따라 달라집니다. ADOT가 원격 측정을 분할하면 콘텐츠는 별도의 이벤트 레코드에 있습니다. 원격 측정이 분할되지 않으면 콘텐츠는 스팬에 인라인 이벤트로 유지됩니다. 자세한 내용은 [스팬, 이벤트 레코드 및 원격 측정 신호를](supported-frameworks-telemetry.md) 참조하세요. 식별 속성(`gen_ai.operation.name`)은 두 경우 모두 스팬에 있습니다.
### 이벤트 레코드에서
원격 측정이 분할되면 서비스는 각 범위와 상관관계가 있는 이벤트 레코드에서 콘텐츠를 읽습니다.
+ **사용자 프롬프트**: 에이전트 입력 메시지(`input.messages`)에서 사용자 역할이 있는 메시지의 콘텐츠입니다.
+ **에이전트 응답**: 에이전트 출력 메시지(`output.messages`)에서 어시스턴트 역할이 있는 메시지의 내용입니다.
+ **도구 호출**: 실행 도구 범위의 `gen_ai.tool.name` 속성에서 도구 이름입니다. 도구 인수와 결과는 해당 스팬의 이벤트 레코드(`input` 및 )에서 가져옵니다`output`.
예제는 [이벤트 레코드가 있는 스팬 예제를 참조하세요](#strands-examples-with).
### 인라인 스팬 이벤트에서
원격 측정이 분할되지 않으면 별도의 이벤트 레코드 대신 인라인 스팬 이벤트에서 동일한 콘텐츠가 전달됩니다.
+ **사용자 프롬프트**: `gen_ai.user.message` 이벤트에서 `content` 속성.
+ **에이전트 응답**: `gen_ai.choice` 이벤트에서 `message` 속성.
+ **도구 호출**: 스팬의 `gen_ai.tool.name` 속성에서 가져온 도구 이름입니다. 도구 인수는 `gen_ai.tool.message` 이벤트에서 가져오고 결과는 `gen_ai.choice` 이벤트에서 가져옵니다.
예제는 [이벤트 레코드가 없는 스팬 예제를 참조하세요](#strands-examples-without).
## 이벤트 레코드가 있는 스팬의 예
원격 측정이 분할되면 스팬은 식별 속성을 전달하고 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. 다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 Strands 여행 계획 에이전트에서 가져온 것입니다.
**참고**
이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.
**Example**
`gen_ai.operation.name` 속성(`invoke_agent`)은 이를 호출 에이전트 범위로 식별합니다. `gen_ai.agent.tools` 속성에는 에이전트가 사용할 수 있는 도구가 나열됩니다.
```
{
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"spanId": "d24936b8989b6d42",
"parentSpanId": "0ff3498548044e4b",
"name": "invoke_agent TravelAgent",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer",
"version": ""
},
"startTimeUnixNano": 1776929864011990383,
"endTimeUnixNano": 1776929869634304466,
"durationNano": 5622314083,
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.system": "strands-agents",
"gen_ai.agent.name": "TravelAgent",
"gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
"gen_ai.usage.input_tokens": 983,
"gen_ai.usage.output_tokens": 232,
"gen_ai.usage.total_tokens": 1215,
"gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
"session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
},
"status": {
"code": "OK"
}
}
```
상관관계가 있는 이벤트 레코드에는 대화 콘텐츠가 포함됩니다. 사용자 프롬프트는의 사용자 역할 메시지`input.messages`이고 에이전트 응답은의 어시스턴트 역할 메시지입니다`output.messages`.
```
{
"spanId": "d24936b8989b6d42",
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"scope": {
"name": "strands.telemetry.tracer"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "Hey, how can you help me"
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": {
"message": "Hi there! I'm your travel planning assistant ...",
"finish_reason": "end_turn"
}
}
]
}
}
}
```
`gen_ai.operation.name` 속성(`execute_tool`)은 이를 실행 도구 범위로 식별합니다. `gen_ai.tool.name` 속성에는 도구 이름이 들어 있습니다.
```
{
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"spanId": "fff785ce12d6fda8",
"parentSpanId": "96915bf5ecc78743",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer",
"version": ""
},
"startTimeUnixNano": 1776929872258292842,
"endTimeUnixNano": 1776929872259611427,
"durationNano": 1318585,
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
"gen_ai.tool.status": "success",
"gen_ai.tool.description": "Search for available flights between cities.",
"session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
},
"status": {
"code": "OK"
}
}
```
상관관계가 있는 이벤트 레코드에는 도구 입력(인수) 및 출력(결과)이 포함됩니다.
```
{
"spanId": "fff785ce12d6fda8",
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"scope": {
"name": "strands.telemetry.tracer"
},
"body": {
"input": {
"messages": [
{
"role": "tool",
"content": {
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"role": "tool",
"id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
}
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": {
"message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
"id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
}
}
]
}
}
}
```
## 이벤트 레코드가 없는 스팬의 예
원격 측정이 분할되지 않으면 별도의 이벤트 레코드 없이 동일한 콘텐츠가 스팬의 인라인 스팬 이벤트에서 전달됩니다. 다음은 Strands 여행 계획 에이전트의 예입니다.
**참고**
이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.
**Example**
`gen_ai.user.message` 이벤트에는 사용자 프롬프트가 저장되고 `gen_ai.choice` 이벤트에는 에이전트 응답이 저장됩니다.
```
{
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"spanId": "d2ee0e4765cc773e",
"name": "invoke_agent TravelAgent",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer"
},
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "TravelAgent",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"events": [
{
"name": "gen_ai.user.message",
"attributes": {
"content": "[{\"text\": \"Hey, how can you help me\"}]"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "Hi there! I'm your travel planning assistant ...",
"finish_reason": "end_turn"
}
}
]
}
```
`gen_ai.tool.message` 이벤트에는 도구 인수가 저장되고 `gen_ai.choice` 이벤트에는 도구 결과가 저장됩니다.
```
{
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"spanId": "0a988e27758ebb53",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer"
},
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
"gen_ai.tool.status": "success",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"events": [
{
"name": "gen_ai.tool.message",
"attributes": {
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"role": "tool",
"id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
"id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
}
}
]
}
```