View a markdown version of this page

AgentCore 평가를 위한 Strands Agents 원격 측정 설정 - Amazon Bedrock AgentCore

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AgentCore 평가를 위한 Strands Agents 원격 측정 설정

이 페이지에서는 Strands Agents 에이전트를 계측하는 방법, 스팬을 식별하는 방법, 평가 필드를 추출하는 방법을 설명합니다.

주제

AgentCore Evaluations는 Python SDK 및 TypeScript SDK로 빌드된 Strands 에이전트를 지원합니다. 두는 서로 다른 범위 이름에서 속성과 콘텐츠 레이아웃을 식별하는 동일한 스팬 유형을 생성하므로 평가 서비스가 동일한 방식으로 읽습니다. 이 페이지에서는 각 언어를 별도로 다룹니다. Python의 경우 Python 에이전트 지원을 참조하고, TypeScript의 경우 TypeScript 에이전트 지원을 참조하세요.

Python 에이전트 지원

Python Strands 에이전트는 범위 이름 아래에 스팬을 생성합니다strands.telemetry.tracer.

에이전트 계측

Strands Agents SDK에는 기본 제공 원격 측정이 포함되어 있으며 추가 계측 라이브러리가 필요하지 않습니다. 범위 이름 로 스팬 및 이벤트 레코드를 생성합니다strands.telemetry.tracer. AWS Distro for OpenTelemetry(ADOT)를 사용하여 Amazon Bedrock AgentCore 런타임에 배포하면 런타임은 session.id 속성을 주입하고 스팬 및 이벤트 레코드를 자동으로 내보냅니다.

참고

계측은 관찰성을 설정하는 한 단계입니다. 평가를 위해 원격 측정을 내보내려면 관찰성 설정에서 전체 설정을 완료합니다.

스팬 식별 방법

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

평가 필드 추출 방법

대화 콘텐츠의 위치는 원격 측정 전송 모드에 따라 달라집니다. 분할 원격 측정을 사용하면 콘텐츠가 별도의 이벤트 레코드에 있습니다. 통합 원격 측정을 사용하면 콘텐츠가 스팬에 연결된 이벤트로 유지됩니다. 자세한 내용은 원격 측정 설정 및 전송을 참조하세요. 식별 속성(gen_ai.operation.name)은 두 모드의 스팬에 있습니다.

이벤트 레코드에서

분할 원격 측정을 사용하면 서비스는 각 범위와 상관관계가 있는 이벤트 레코드에서 콘텐츠를 읽습니다.

  • 사용자 프롬프트: 에이전트 입력 메시지(input.messages)에서 사용자 역할이 있는 메시지의 콘텐츠입니다.

  • 에이전트 응답: 에이전트 출력 메시지(output.messages)에서 어시스턴트 역할이 있는 메시지의 내용입니다.

  • 도구 호출: 실행 도구 범위의 gen_ai.tool.name 속성에서 도구 이름입니다. 도구 인수와 결과는 해당 스팬의 이벤트 레코드(input 및 )에서 가져옵니다output.

자세한 내용은 분할 원격 측정의 스팬 예제를 참조하세요.

인라인 스팬 이벤트에서

통합 원격 측정을 사용하면 별도의 이벤트 레코드 대신 인라인 스팬 이벤트에서 동일한 콘텐츠가 전달됩니다.

  • 사용자 프롬프트: gen_ai.user.message 이벤트에서 content 속성.

  • 에이전트 응답: gen_ai.choice 이벤트에서 message 속성.

  • 도구 호출: 스팬의 gen_ai.tool.name 속성에서 가져온 도구 이름입니다. 도구 인수는 gen_ai.tool.message 이벤트에서 가져오고 결과는 gen_ai.choice 이벤트에서 가져옵니다.

자세한 내용은 통합 원격 측정의 스팬 예제를 참조하세요.

분할 원격 측정의 스팬 예제

분할 원격 측정을 사용하면 스팬은 식별 속성을 전달하고 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. 다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 Python Strands 여행 계획 에이전트에서 가져온 것입니다.

참고

이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.

예
Invoke agent span

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" } } ] } } }
Execute tool span

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" } } ] } } }

통합 원격 측정의 스팬 예제

통합 원격 측정을 사용하면 별도의 이벤트 레코드 없이 동일한 콘텐츠가 스팬의 인라인 스팬 이벤트에서 전달됩니다. 다음은 Python Strands 여행 계획 에이전트의 예입니다.

참고

이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.

예
Invoke agent span

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" } } ] }
Execute tool span

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" } } ] }

TypeScript 에이전트 지원

TypeScript Strands 에이전트는 범위 이름 아래에 스팬을 생성합니다strands-agents. Python 에이전트와 동일한 스팬 유형 및 콘텐츠 레이아웃을 내보내므로 평가 서비스가 동일한 방식으로 읽습니다.

에이전트 계측

TypeScript Strands Agents SDK(@strands-agents/sdk>= 1.5.0)에는 기본 제공 원격 측정이 포함되어 있으며 추가 계측 라이브러리가 필요하지 않습니다. AWS Distro for OpenTelemetry(ADOT)를 사용하여 Amazon Bedrock AgentCore 런타임에 배포하면 런타임이 session.id 속성을 주입하고 스팬 및 이벤트 레코드를 자동으로 내보냅니다. TypeScript SDK는 범위 이름 아래에 스팬을 생성합니다strands-agents.

참고

계측은 관찰성을 설정하는 한 단계입니다. 평가를 위해 원격 측정을 내보내려면 관찰성 설정에서 전체 설정을 완료합니다.

스팬 식별 방법

스팬 식별은 Python 에이전트와 동일합니다. gen_ai.operation.name 속성은 각 스팬을 분류합니다. 값 및 예제 범위 이름은 Python 지원에서 범위를 식별하는 방법을 참조하세요.

평가 필드 추출 방법

필드 추출은 Python 에이전트와 동일합니다. 대화 콘텐츠는 인라인 스팬 이벤트(gen_ai.user.message, gen_ai.choice및 gen_ai.tool.message)로 전달됩니다. 각 필드를 읽는 위치에 대한 자세한 내용은 Python 지원의 인라인 스팬 이벤트에서를 참조하세요.

TypeScript 에이전트의 범위 예

다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 TypeScript Strands 여행 계획 에이전트에서 가져온 것입니다.

참고

이 예제는 완전한 범위가 아닙니다. 실제 에이전트 상호 작용의 대표 데이터를 표시하며, 일부 필드는 생략되고 긴 값은 가독성을 위해 잘립니다.

예
Invoke agent span

gen_ai.operation.name 속성(invoke_agent)은 이를 호출 에이전트 범위로 식별하고 에이전트가 사용할 수 있는 도구를 gen_ai.agent.tools 나열합니다. gen_ai.user.message 이벤트에는 사용자 프롬프트가 저장되고 gen_ai.choice 이벤트에는 에이전트 응답이 저장됩니다.

{ "traceId": "6a6bc695459e41aa14a172bb41d3246d", "spanId": "c2c44e69bdab6ef1", "parentSpanId": "f18d96d107e793ba", "name": "invoke_agent Strands Agent", "kind": "INTERNAL", "scope": { "name": "strands-agents", "version": "" }, "attributes": { "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": "Strands Agent", "gen_ai.system": "strands-agents", "gen_ai.request.model": "global.anthropic.claude-sonnet-4-5-20250929-v1:0", "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]", "session.id": "sea-nyc-trip-2-turns" }, "events": [ { "name": "gen_ai.user.message", "attributes": { "content": "[{\"text\": \"Hey, how can you help me\"}]" } }, { "name": "gen_ai.choice", "attributes": { "message": "Hello! I'm your travel planning assistant, and I can help you with the following: ..." } } ] }
Execute tool span

gen_ai.operation.name 속성(execute_tool)은 이를 실행 도구 범위로 식별합니다.는 도구 이름을 gen_ai.tool.name 보유합니다. gen_ai.tool.message 이벤트에는 도구 인수가 저장되고 gen_ai.choice 이벤트에는 도구 결과가 저장됩니다.

{ "traceId": "6a6bc69e6eaa1e994481bef349f4c72e", "spanId": "4227ac5525f22dd2", "parentSpanId": "8a989e0dbb9dc22f", "name": "execute_tool search_flights", "kind": "INTERNAL", "scope": { "name": "strands-agents", "version": "" }, "attributes": { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": "search_flights", "gen_ai.tool.call.id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ", "gen_ai.tool.status": "success", "session.id": "sea-nyc-trip-2-turns" }, "events": [ { "name": "gen_ai.tool.message", "attributes": { "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}", "role": "tool", "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ" } }, { "name": "gen_ai.choice", "attributes": { "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]", "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ" } } ] }