View a markdown version of this page

Strands Agents - Amazon Bedrock AgentCore

Strands Agents

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

주제

에이전트 계측

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

평가 필드 추출 방법

대화 콘텐츠의 위치는 원격 측정이 수집된 방식에 따라 달라집니다. ADOT가 원격 측정을 분할하면 콘텐츠는 별도의 이벤트 레코드에 있습니다. 원격 측정이 분할되지 않으면 콘텐츠는 스팬에 인라인 이벤트로 유지됩니다. 자세한 내용은 스팬, 이벤트 레코드 및 원격 측정 신호를 참조하세요. 식별 속성(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 런타임에 배포된 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" } } ] } } }

이벤트 레코드가 없는 스팬의 예

원격 측정이 분할되지 않으면 별도의 이벤트 레코드 없이 동일한 콘텐츠가 스팬의 인라인 스팬 이벤트에서 전달됩니다. 다음은 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" } } ] }