에이전트 계측 스팬 식별 방법 평가 필드 추출 방법 이벤트 레코드가 있는 스팬의 예 이벤트 레코드가 없는 스팬의 예

OpenAI 에이전트

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

주제

에이전트 계측
스팬 식별 방법
평가 필드 추출 방법
- 이벤트 레코드에서
- 스팬 속성에서
이벤트 레코드가 있는 스팬의 예
이벤트 레코드가 없는 스팬의 예

에이전트 계측

OpenTelemetry(opentelemetry-instrumentation-openai-agents) 또는 OpenInference()의 두 가지 계측 라이브러리 중 하나를 사용하여 OpenAI Agents 에이전트를 계측할 수 있습니다openinference-instrumentation-openai-agents. Amazon Bedrock AgentCore Evaluations는 두 라이브러리를 모두 지원합니다. 라이브러리는 서로 다른 범위 이름을 내보내고 서로 다른 스팬 속성을 사용합니다. 평가 서비스는 각각에서 동일한 값을 추출합니다.

Amazon Bedrock AgentCore 런타임에서와 같이 에이전트가 AWS Distro for OpenTelemetry(ADOT)를 사용하여 실행되는 경우 명시적 계측 코드를 추가할 필요가 없습니다. 프로젝트의 종속성에 계측 라이브러리를 추가하면 충분합니다. ADOT는 시작 시 이를 검색하고 자동으로 활성화합니다.

종속성에 원하는 경로의 계측 라이브러리를 추가합니다. 고정할 이유가 없는 한 사용 가능한 최신 버전을 사용합니다.

예

참고

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

스팬 식별 방법

스팬을 분류하는 데 사용되는 속성은 두 계측 라이브러리 간에 다릅니다.

예

OpenTelemetry

OpenTelemetry 계측 라이브러리는 gen_ai.operation.name 속성을 사용하여 스팬을 분류합니다.

범위 유형	속성 식별
에이전트 호출	`gen_ai.operation.name` = `invoke_agent`
도구 실행	`gen_ai.operation.name` = `execute_tool`
Inference	`gen_ai.operation.name` = `chat`

참고

OpenAI 에이전트는 gen_ai.operation.name = 인 내부 회전 경계 범위도 내보냅니다unknown. 평가 서비스는 이를 건너뜁니다.

OpenInference

OpenInference 계측 라이브러리는 openinference.span.kind 속성을 사용하여 스팬을 분류합니다.

범위 유형	속성 식별
에이전트 호출	`openinference.span.kind` = `AGENT` 또는 `CHAIN`
도구 실행	`openinference.span.kind` = `TOOL`
Inference	`openinference.span.kind` = `LLM`

참고

OpenInference 라이브러리에서 AGENT 및 CHAIN스팬은 빈 구조 컨테이너이며 대화 콘텐츠를 포함하지 않습니다. 사용자 프롬프트와 에이전트 응답은 동일한 추적의 추론(LLM) 스팬에서 재구성됩니다.

평가 필드 추출 방법

OpenAI Agents는 각 메시지에 입력된 콘텐츠 블록 parts 배열(예: )이 포함된 부분 기반 형식으로 메시지를 직렬화합니다[{"role": "user", "parts": [{"type": "text", "content": "…"}]}]. OpenTelemetry 라이브러리를 사용하면 AgentCore Evaluations가 이러한 부분에서 텍스트를 구문 분석합니다. OpenInference 라이브러리를 사용하면 모델 출력이 전체 OpenAI 응답 객체이며 AgentCore Evaluations는에서 응답 텍스트를 읽습니다output[].content[].text.

이 콘텐츠의 위치는 원격 측정이 수집된 방식에 따라 달라집니다. 식별 속성(gen_ai.operation.name 또는 openinference.span.kind)은 두 경우 모두 스팬에 있습니다. 자세한 내용은 스팬, 이벤트 레코드 및 원격 측정 신호를 참조하세요.

이벤트 레코드에서

원격 측정이 분할되면 AgentCore Evaluations는 각 범위와 상관관계가 있는 이벤트 레코드에서 대화 콘텐츠를 읽습니다. 도구 입력 및 출력의 위치는 두 라이브러리 간에 다릅니다.

OpenTelemetry:
- 사용자 프롬프트 및 에이전트 응답: body.input 및의 에이전트 스팬 호출 이벤트 레코드에서body.output.
- 도구 호출:의 도구 이름과 gen_ai.tool.call.result 실행 도구 범위의 gen_ai.tool.name인수 gen_ai.tool.call.arguments 및 결과입니다. OpenTelemetry 라이브러리를 사용하면 원격 측정이 분할되더라도 도구 인수와 결과가 스팬 속성에 남아 있습니다.
OpenInference:
- 사용자 프롬프트 및 에이전트 응답: 추론 범위의 이벤트 레코드에서 재구성됩니다. AgentCore Evaluations는 body.input 및에서 메시지를 읽은 body.output다음 빈 호출 에이전트 범위를 사용자 프롬프트 및 에이전트 응답으로 채웁니다.
- 도구 호출: 실행 도구 범위의 tool.name에서 도구 이름입니다. 도구 인수와 결과는 body.input 및의 해당 스팬의 이벤트 레코드에서 가져옵니다body.output.

예제는 이벤트 레코드가 있는 스팬 예제를 참조하세요.

스팬 속성에서

원격 측정이 분할되지 않으면 속성과 동일한 콘텐츠가 스팬에 유지됩니다. 속성은 계측 라이브러리에 따라 다릅니다.

OpenTelemetry:
- 사용자 프롬프트 및 에이전트 응답: 에이전트 간접 호출 스팬에서 gen_ai.input.messages 및 gen_ai.output.messages에서.
- 도구 호출: gen_ai.tool.call.result실행 도구 범위의의 도구 이름과 및의 gen_ai.tool.name인수 gen_ai.tool.call.arguments 및 결과입니다.
OpenInference:
- 사용자 프롬프트 및 에이전트 응답: 추론 범위(llm.input_messages. 및 llm.output_messages.)의 인덱싱된 메시지 속성에서 가져온 다음 빈 간접 호출 에이전트 범위로 다시 채워집니다.
- 도구 호출: output.value실행 도구 범위의의 도구 이름과 및의 tool.name인수 input.value 및 결과입니다.

예제는 이벤트 레코드가 없는 스팬 예제를 참조하세요.

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

원격 측정이 분할되면 스팬은 식별 속성을 전달하고 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. 다음 예제는 Amazon Bedrock AgentCore 런타임에 배포된 OpenAI Agents 여행 계획 에이전트에서 가져온 것입니다. 각 계측 라이브러리 아래에 동일한 에이전트가 표시됩니다.

참고

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

OpenTelemetry

예

Invoke agent span

gen_ai.operation.name 속성(invoke_agent)은 이를 호출 에이전트 범위로 식별합니다.


{
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "spanId": "3a300b0b3fe650e4",
  "name": "invoke_agent openaiOtelTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "openaiOtelTravel",
    "gen_ai.system": "openai",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}

상관관계가 있는 이벤트 레코드에는 대화가 포함됩니다. 각 메시지의 content는 OpenAI 부분 형식 배열이며, 사용자 프롬프트는 사용자 메시지의 텍스트이고 에이전트 응답은 어시스턴트 메시지의 텍스트입니다.


{
  "spanId": "3a300b0b3fe650e4",
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
        }
      ]
    }
  }
}

Execute tool span

gen_ai.operation.name 속성(execute_tool)은 이를 실행 도구 범위로 식별합니다.는 도구 이름을 gen_ai.tool.name 보유합니다. OpenTelemetry 라이브러리를 사용하면 원격 측정이 분할되더라도 도구 인수와 결과가 스팬 속성에 유지됩니다.


{
  "traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
  "spanId": "3cbc4ea5f73fef81",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

gen_ai.operation.name 속성(chat)은 이를 추론 범위로 식별합니다. 이 범위에는 모델 메타데이터와에서 에이전트가 사용할 수 있는 도구 gen_ai.tool.definitions목록이 포함됩니다. 모델 호출에 대한 대화 메시지는 body.input 및의 상관관계가 있는 이벤트 레코드에 표시됩니다body.output.


{
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "spanId": "7c1f9a2b4d6e8a03",
  "name": "openai.response",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.response.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.usage.input_tokens": 269,
    "gen_ai.usage.output_tokens": 78,
    "gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "7c1f9a2b4d6e8a03",
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
        }
      ]
    }
  }
}

OpenInference

OpenInference 라이브러리에서 에이전트 호출(AGENT) 스팬은 빈 컨테이너입니다. AgentCore Evaluations는 콘텐츠가 상관관계가 있는 이벤트 레코드에 있는 추론(LLM) 범위의 사용자 프롬프트와 에이전트 응답을 재구성합니다.

예

Invoke agent span

openinference.span.kind 속성(AGENT)은 이를 호출 에이전트 범위로 식별합니다. 스팬에는 대화 콘텐츠가 없습니다.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "9a1c7dce81b692cd",
  "name": "openaiOInfTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "graph.node.id": "openaiOInfTravel",
    "llm.system": "openai",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

openinference.span.kind 속성(TOOL)은 이를 실행 도구 범위로 식별합니다.는 도구 이름을 tool.name 보유합니다. 도구 인수와 결과는 상관관계가 있는 이벤트 레코드에 있습니다.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "b4e78cb0a06a6fe2",
  "name": "search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "search_flights",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "b4e78cb0a06a6fe2",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        { "role": "assistant", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}" }
      ]
    }
  }
}

Inference span

openinference.span.kind 속성(LLM)은 이를 추론 범위로 식별합니다. 메시지 역할 및 도구 정의는 범위 속성에 있으며, 메시지 콘텐츠는 상관관계가 있는 이벤트 레코드에 있습니다. ADOT는 입력 역할을 로 평면화user하므로 AgentCore Evaluations는 마지막 일반 텍스트 입력 메시지를 사용자 프롬프트로 사용합니다. 출력 메시지는 AgentCore Evaluations가 응답 텍스트를 읽는 OpenAI 응답 객체입니다.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1221a062c7f90a8e",
  "name": "response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "llm.model_name": "gpt-4o-mini-2024-07-18",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.output_messages.0.message.role": "assistant",
    "llm.tools.0.tool.json_schema": "{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", ...}}",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "1221a062c7f90a8e",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "[{\"content\": \"Hey, how can you help me\", \"role\": \"user\"}]" },
        { "role": "user", "content": "You are a travel planning assistant. Help users plan trips ..." },
        { "role": "user", "content": "Hey, how can you help me" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"resp_abc123...\", \"output\": [{\"type\": \"message\", \"content\": [{\"type\": \"output_text\", \"text\": \"I can assist you with planning your trips ...\"}]}]}"
        }
      ]
    }
  }
}

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

원격 측정이 분할되지 않으면 동일한 콘텐츠가 스팬 속성에 유지되고 별도의 이벤트 레코드가 생성되지 않습니다. 다음은 OpenAI Agents 여행 계획 에이전트의 예입니다. 각 계측 라이브러리 아래에 동일한 에이전트가 표시됩니다.

참고

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

OpenTelemetry

예

Invoke agent span

gen_ai.input.messages 속성에는 사용자 프롬프트가 있고 gen_ai.output.messages 속성에는 에이전트 응답이 있습니다. 둘 다 OpenAI 부분 형식 배열입니다.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "50656fd77904d125",
  "name": "invoke_agent openaiOtelTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "openaiOtelTravel",
    "gen_ai.system": "openai",
    "gen_ai.input.messages": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]",
    "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

gen_ai.tool.call.arguments 속성에는 도구 인수가 있고 gen_ai.tool.call.result 속성에는 도구 결과가 있습니다.


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "8840e8e23724ebd7",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

gen_ai.operation.name 속성(chat)은 이를 추론 범위로 식별합니다. 모델 메타데이터와 gen_ai.tool.definitions 속성(에이전트가 사용할 수 있는 도구 목록)은 범위 내에서 인라인으로 유지됩니다.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "9b2c1e5f7a3d0846",
  "name": "openai.response",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.response.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.usage.input_tokens": 269,
    "gen_ai.usage.output_tokens": 78,
    "gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

OpenInference

예

Execute tool span

input.value 속성에는 도구 인수가 있고 output.value 속성에는 도구 결과가 있습니다.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "d5a1c9e70b46f312",
  "name": "search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.1"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "search_flights",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-oi"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

메시지 콘텐츠는 인덱싱된 속성에 인라인입니다. llm.input_messages. 속성에는 시스템 프롬프트와 사용자 프롬프트가 저장되고 llm.output_messages. 속성에는 에이전트 응답이 저장됩니다. AgentCore Evaluations는이 범위의 사용자 프롬프트와 에이전트 응답을 재구성하고 빈 간접 호출 에이전트(AGENT) 범위를 채웁니다.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "c9f0a2b41d773e88",
  "name": "response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.1"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "llm.model_name": "gpt-4o-mini-2024-07-18",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.0.message.content": "You are a travel planning assistant ...",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.content": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "assistant",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can assist you with planning your trips ...",
    "session.id": "sea-nyc-trip-2-turns-oi"
  },
  "status": {
    "code": "OK"
  }
}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

LangGraph

LlamaIndex