View a markdown version of this page

Eingabebereiche verstehen - Amazon Grundgestein AgentCore
Zeitspannen und EreignisseBeispiele für Zeitspannen und Ereignisse

Eingabebereiche verstehen

Die evaluate API akzeptiert eine Liste vonsessionSpans, die aus zwei Arten von Entitäten besteht: Spans und Events

Zeitspannen und Ereignisse

Der Bewertungsservice verarbeitet zwei Arten von Telemetriedaten, um das Verhalten und die Leistung Ihres Agenten zu verstehen.

Spans

Spans enthalten Metadaten zu einzelnen Vorgängen, darunter Attribute, Bereichsinformationen, Zeitstempel und Ressourcen-Identifikatoren. Spans sind in der Protokollgruppe verfügbar. aws/spans

Ereignisse

Ereignisse enthalten Nutzdateninformationen im body Feld, einschließlich Eingaben und Ausgaben von Modellen, Tools und dem Agenten. Bei auf AgentCore Runtime gehosteten Agenten werden Ereignisse in einer /aws/bedrock-agentcore/runtimes/agent_id-endpoint_name Protokollgruppe gespeichert. Für Agenten, die außerhalb von AgentCore Runtime gehostet werden, werden Ereignisse in der Protokollgruppe gespeichert, die anhand der OTEL_EXPORTER_OTLP_LOGS_HEADERS Umgebungsvariablen konfiguriert ist.

Anmerkung

Um eine Sitzung auszuwerten, sind sowohl Spans als auch die entsprechenden Ereignisse erforderlich. Nicht alle Spans werden Ereignisse enthalten, aber diejenigen mit den unterstützten Bereichen sollten entsprechende Ereignisse enthalten, da der Service sonst ein Ereignis auslöst. ValidationException

Struktur der Spanne

Die Spans folgen einer standardisierten Struktur mit erforderlichen und optionalen Feldern, die Kontext zu den Vorgängen in Ihrem Agenten-Workflow bieten.

Variationen von Attributen

Die in Span-Attributen enthaltenen Informationen variieren je nach verwendetem Agent-Framework und verwendeter Instrumentierungsbibliothek.

Unterstützte Bereiche

Der Bereichsname bestimmt, ob der Dienst den Bereich verarbeiten kann. Die folgenden Bereiche werden derzeit unterstützt:

  • 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"
        }
    },
}

Ereignisstruktur

Span-Ereignisse werden mit Spans verknüpft, die und verwendenspanId. traceId Anhand des Bereichsnamens des Ereignisses wird bestimmt, ob es die für die Auswertung erforderlichen Informationen enthält.

{
    "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",
}

Schema des Hauptteils des Ereignisses

Bei Ereignissen mit unterstützten Bereichen folgt das body Feld diesem Schema. Die tatsächlichen Werte im Inhaltsfeld variieren je nach verwendetem Framework und verwendeter Instrumentierungsbibliothek. 

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

Beispiele für Zeitspannen und Ereignisse

Im Folgenden finden Sie Beispiele für Zeitspannen und die entsprechenden Ereignisse für den in AgentCore Runtime erstellten und bereitgestellten Demo-Agenten, wie im Leitfaden „Erste Schritte“ beschrieben. Die Beispiele zeigen

  • InvokeAgent Spannweiten, die für Bewertungen auf Spurenebene verwendet wurden

  • ExecuteTool Spannweiten, die für Evaluierungen auf Toolebene verwendet werden

Beispiel
Strands Agents

  1. "gen_ai.operation.name": "invoke_agent"Das Attribut wird verwendet, um Zeiträume für Agentenaufrufe zu identifizieren

    ## 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. Das Attribut "traceloop.span.kind": "workflow" wird verwendet, um Zeiträume für Agentenaufrufe zu identifizieren

    {
  "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. Das Attribut "traceloop.span.kind": "tool" wird verwendet, um Zeiträume für die Ausführung von Tools zu identifizieren

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