View a markdown version of this page

입력 범위 이해 - Amazon Bedrock AgentCore
스팬 및 이벤트스팬 및 이벤트 예제

입력 범위 이해

evaluate API는 sessionSpans 스팬 및 이벤트라는 두 가지 유형의 엔터티로 구성된 목록을 허용합니다.

스팬 및 이벤트

평가 서비스는 에이전트의 동작과 성능을 이해하기 위해 두 가지 유형의 원격 측정 데이터를 처리합니다.

스팬

스팬에는 속성, 범위 정보, 타임스탬프, 리소스 식별자 등 개별 작업에 대한 메타데이터가 포함되어 있습니다. 스팬은 aws/spans 로그 그룹에서 사용할 수 있습니다.

이벤트

이벤트에는 모델, 도구 및 에이전트의 입력 및 출력을 포함하여 body 필드의 페이로드 정보가 포함됩니다. AgentCore 런타임에서 호스팅되는 에이전트의 경우 이벤트는 /aws/bedrock-agentcore/runtimes/agent_id-endpoint_name 로그 그룹에 저장됩니다. AgentCore 런타임 외부에서 호스팅되는 에이전트의 경우 이벤트는 OTEL_EXPORTER_OTLP_LOGS_HEADERS 환경 변수로 구성된 로그 그룹에 저장됩니다.

참고

세션을 평가하려면 범위와 해당 이벤트가 모두 필요합니다. 모든 스팬에 이벤트가 있는 것은 아니지만 지원되는 범위가 있는 스팬에는 해당 이벤트가 포함되어야 합니다. 그렇지 않으면 서비스가를 발생시킵니다ValidationException.

스팬 구조

스팬은 에이전트 워크플로의 작업에 대한 컨텍스트를 제공하는 필수 및 선택적 필드가 있는 표준화된 구조를 따릅니다.

속성 변형

스팬 속성에 있는 정보는 사용된 에이전트 프레임워크 및 계측 라이브러리에 따라 다릅니다.

지원되는 범위

범위 이름에 따라 서비스가 스팬을 처리할 수 있는지 여부가 결정됩니다. 현재 지원되는 범위는 다음과 같습니다.

  • strands.telemetry.tracer

  • opentelemetry.instrumentation.langchain

  • openinference.instrumentation.langchain 

{
    "spanId": "string"                 ## required
    "traceId": "string",               ## required
    "parentSpanId": "string",
    "name": "string"                   ## required
    "scope": {
        "name": "string"               ## required
    },
    "startTimeUnixNano": "epoch time", ## required
    "endTimeUnixNano": "epoch time",   ## required
    "durationNano": "epoch time",
    "attributes": {                    ## required
        "session.id": "string",        ## required
        "string": "string"
    },
    "status": {
        "code": "string"
    },
    "kind": "string",
    "resource": {
        "attributes": {
            "string": "string",
            "string": "string"
        }
    },
}

이벤트 구조

스팬 이벤트는 spanId 및를 사용하여 traceId 스팬과 연결됩니다. 이벤트의 범위 이름은 평가에 필요한 정보가 포함되어 있는지 여부를 결정하는 데 사용됩니다.

{
    "spanId": "string",         ## required
    "traceId": "string",        ## required
    "scope": {
        "name": "string"        ## required
    },
    "body": "Any",              ## required for supported scopes (refer below section)
    "attributes": {
        "event.name": "string", ## required
        "session.id": "string"  ## required
    },
    "resource": {
        "attributes": {
            "string": "string",
            "string": "string"
        }
    },
    "timeUnixNano": "epoch time",
    "observedTimeUnixNano": "epoch time",
    "severityNumber": "int",
    "severityText": "string",
}

이벤트 본문 스키마

지원되는 범위가 있는 이벤트의 경우 body 필드는이 스키마를 따릅니다. 콘텐츠 필드의 실제 값은 사용된 프레임워크 및 계측 라이브러리에 따라 달라집니다.

{
    "body": {
        "output": {
            "messages": [
                {
                    "content": "string/dict" # depends on framework/instrumentation
                    "role": "string"
                }
            ]
        },
        "input": {
            "messages": [
                {
                    "content": "string/dict" # depends on framework/instrumentation
                    "role": "string"
                }
            ]
        }
    }
}

스팬 및 이벤트 예제

다음은 시작 안내서에 따라 AgentCore 런타임에서 생성 및 배포된 데모 에이전트에 대한 예제 범위 및 해당 이벤트입니다. 이 예제에서는 다음을 보여줍니다.

  • 트레이스 수준 평가에 사용되는 InvokeAgent 스팬

  • 도구 수준 평가에 사용되는 ExecuteTool 스팬

예
Strands Agents

  1. 속성"gen_ai.operation.name": "invoke_agent"은 에이전트 호출 범위를 식별하는 데 사용됩니다.

    ## Example invoke_agent span for strands agent
{
  "spanId": "e79d2156ac138f63",
  "traceId": "691e400b638f5225711e80da37a4b0bd",
  "resource": {
      "attributes": {
          "deployment.environment.name": "bedrock-agentcore:default",
          "aws.local.service": "agentcore_evaluation_demo.DEFAULT",
          "service.name": "agentcore_evaluation_demo.DEFAULT",
          "cloud.region": "us-east-1",
          "aws.log.stream.names": "otel-rt-logs",
          "telemetry.sdk.name": "opentelemetry",
          "aws.service.type": "gen_ai_agent",
          "telemetry.sdk.language": "python",
          "cloud.provider": "aws",
          "cloud.resource_id": "agent-arn",
          "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/agent-id",
          "telemetry.sdk.version": "1.33.1",
          "cloud.platform": "aws_bedrock_agentcore",
          "telemetry.auto.version": "0.12.2-aws"
      }
  },
  "scope": {
      "name": "strands.telemetry.tracer",
      "version": ""
  },

  "parentSpanId": "ec3c4c7fb2603f7a",
  "flags": 256,
  "name": "invoke_agent Strands Agents",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763590155895947177,
  "endTimeUnixNano": 1763590165204959446,
  "durationNano": 9309012269,
  "attributes": {
      "aws.local.service": "agentcore_evaluation_demo.DEFAULT",
      "gen_ai.usage.prompt_tokens": 2021,
      "gen_ai.usage.output_tokens": 320,
      "gen_ai.usage.cache_write_input_tokens": 0,
      "gen_ai.agent.name": "Strands Agents",
      "gen_ai.usage.total_tokens": 2341,
      "gen_ai.usage.completion_tokens": 320,
      "gen_ai.event.start_time": "2025-11-19T22:09:15.895962+00:00",
      "aws.local.environment": "bedrock-agentcore:default",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.event.end_time": "2025-11-19T22:09:25.204930+00:00",
      "gen_ai.usage.input_tokens": 2021,
      "gen_ai.request.model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
      "gen_ai.usage.cache_read_input_tokens": 0,
      "gen_ai.agent.tools": "[\"analyze_text\", \"get_word_frequency\"]",
      "PlatformType": "AWS::BedrockAgentCore",
      "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
      "gen_ai.system": "strands-agents",
      "gen_ai.tool.definitions": "[{\"name\": \"analyze_text\", \"description\": \"Analyze text and provide statistics about it.\", \"inputSchema\": {\"json\": {\"properties\": {\"text\": {\"description\": \"Parameter text\", \"type\": \"string\"}}, \"required\": [\"text\"], \"type\": \"object\"}}, \"outputSchema\": null}, {\"name\": \"get_word_frequency\", \"description\": \"Get the frequency of words in the provided text.\", \"inputSchema\": {\"json\": {\"properties\": {\"text\": {\"description\": \"Parameter text\", \"type\": \"string\"}, \"top_n\": {\"default\": 5, \"description\": \"Parameter top_n\", \"type\": \"integer\"}}, \"required\": [\"text\"], \"type\": \"object\"}}, \"outputSchema\": null}]"
  },
  "status": {
      "code": "OK"
  }
}
Langgraph (with opentelemetry-instrumentation)

  1. 속성"traceloop.span.kind": "workflow"은 에이전트 호출 범위를 식별하는 데 사용됩니다.

    {
  "resource": {
    "attributes": {
      "deployment.environment.name": "bedrock-agentcore:default",
      "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
      "service.name": "agentcore_evaluation_demo_lg.DEFAULT",
      "cloud.region": "us-east-1",
      "aws.log.stream.names": "otel-rt-logs",
      "telemetry.sdk.name": "opentelemetry",
      "aws.service.type": "gen_ai_agent",
      "telemetry.sdk.language": "python",
      "cloud.provider": "aws",
      "cloud.resource_id": "<agent-arn>",
      "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/<agent-id>",
      "telemetry.sdk.version": "1.33.1",
      "cloud.platform": "aws_bedrock_agentcore",
      "telemetry.auto.version": "0.14.0-aws"
    }
  },
  "scope": {
    "name": "opentelemetry.instrumentation.langchain",
    "version": "0.48.1"
  },
  "traceId": "691f4a5c0a7ab761407a1a9a36991613",
  "spanId": "298f3169bdca46d8",
  "parentSpanId": "737921ed52222e5d",
  "flags": 256,
  "name": "LangGraph.workflow",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763658333042983700,
  "endTimeUnixNano": 1763658340533358800,
  "durationNano": 7490375269,
  "attributes": {
    "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
    "traceloop.span.kind": "workflow",
    "traceloop.workflow.name": "LangGraph",
    "traceloop.entity.name": "LangGraph",
    "PlatformType": "AWS::BedrockAgentCore",
    "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
    "traceloop.entity.path": "",
    "aws.local.environment": "bedrock-agentcore:default"
  },
  "status": {
    "code": "UNSET"
  }
}
ExecuteTool span

  1. 속성"traceloop.span.kind": "tool"은 도구 실행 범위를 식별하는 데 사용됩니다.

    ## tool span
{
  "traceId": "691f4a5c0a7ab761407a1a9a36991613",
  "spanId": "b58bd6568e00fc64",
  "parentSpanId": "aaee94b5bd16f3b0",
  "scope": {
    "name": "opentelemetry.instrumentation.langchain",
    "version": "0.48.1"
  },
  "flags": 256,
  "name": "get_word_frequency.tool",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763658336583727000,
  "endTimeUnixNano": 1763658336584260400,
  "durationNano": 533416,
  "attributes": {
    "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
    "traceloop.span.kind": "tool",
    "traceloop.workflow.name": "LangGraph",
    "traceloop.entity.name": "get_word_frequency",
    "PlatformType": "AWS::BedrockAgentCore",
    "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
    "traceloop.entity.path": "tools",
    "aws.local.environment": "bedrock-agentcore:default"
  },
  "status": {
    "code": "UNSET"
  },
  "resource": {
    "attributes": {
      "deployment.environment.name": "bedrock-agentcore:default",
      "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
      "service.name": "agentcore_evaluation_demo_lg.DEFAULT",
      "cloud.region": "us-east-1",
      "aws.log.stream.names": "otel-rt-logs",
      "telemetry.sdk.name": "opentelemetry",
      "aws.service.type": "gen_ai_agent",
      "telemetry.sdk.language": "python",
      "cloud.provider": "aws",
      "cloud.resource_id": "<agent-arn>",
      "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/<agent-id>",
      "telemetry.sdk.version": "1.33.1",
      "cloud.platform": "aws_bedrock_agentcore",
      "telemetry.auto.version": "0.14.0-aws"
    }
  }
}