trace를 사용하여 에이전트의 단계별 추론 프로세스 추적 - Amazon Bedrock
추적의 구조

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

trace를 사용하여 에이전트의 단계별 추론 프로세스 추적

Amazon Bedrock 에이전트의 각 응답에는 에이전트가 오케스트레이션한 단계를 자세히 설명하는 추적 정보가 함께 제공됩니다. 추적은 대화의 해당 시점에서 응답으로 이어지는 에이전트의 추론 프로세스를 추적하는 데 도움이 됩니다.

추적을 사용하면 사용자 입력부터 반환되는 응답까지 에이전트의 경로를 추적할 수 있습니다. 추적은 에이전트가 간접 호출하는 작업 그룹에 대한 입력과 사용자에게 응답하기 위해 쿼리하는 지식 기반에 대한 정보를 제공합니다. 또한 추적은 작업 그룹과 지식 기반이 반환하는 출력에 대한 정보를 제공합니다. 에이전트가 수행하는 조치 또는 지식 기반에 적용하는 쿼리를 결정하는 데 사용하는 추론을 볼 수 있습니다. 추적의 어떤 단계가 실패할 경우, 추적에서는 실패 사유를 반환합니다. 추적의 세부 정보를 사용하여 에이전트 문제를 해결합니다. 에이전트에 문제가 발생하거나 예기치 않은 동작이 발생하는 단계를 식별할 수 있습니다. 그런 다음 이 정보를 사용하여 에이전트의 동작을 개선할 방법을 고려할 수 있습니다.

추적의 구조

추적을 활성화하면 InvokeAgent 응답에서 스트림의 각 chunk에 TracePart 객체에 매핑되는 trace 필드가 함께 표시됩니다. tracePart 객체에는 에이전트의 추론 프로세스 및 API 함수 호출 결과와 함께 에이전트 및 세션에 대한 정보가 포함됩니다.

{
    "agentId": "string",
    "agentName": "string",
    "collaboratorName": "string",
    "agentAliasId": "string",
    "sessionId": "string",
    "agentVersion": "string",
    "trace": { ...},    
    "callerChain": [{
        "agentAliasArn": "agent alias arn"
    }]
}

다음 목록은 TracePart 객체의 필드를 설명합니다.

  • agentId - 에이전트의 고유 식별자입니다.

  • agentName - 에이전트의 이름입니다.

  • collaboratorName - 다중 에이전트 공동 작업이 활성화된 경우 공동 작업자 에이전트의 이름입니다.

  • agentVersion - 에이전트의 버전입니다.

  • agentAliasId - 에이전트 별칭의 고유 식별자입니다.

  • sessionId - 에이전트와의 세션의 고유 식별자입니다.

  • trace - 에이전트의 추론 프로세스와 API 작업을 호출한 결과를 포함합니다. 자세한 내용은 아래를 참조하세요.

  • callerChain -이 추적을 게시한 에이전트와 최종 사용자 간의 호출자 목록입니다.

    • 단일 에이전트인 경우이 필드에는 트레이스를 게시한 동일한 에이전트의 별칭 Arn이 포함됩니다.

    • 다중 에이전트 공동 작업이 활성화된 경우이 필드에는 최종 사용자 요청을 현재 에이전트에 전달한 모든 에이전트의 별칭 Arn이 포함됩니다.

TracePart 내에는 Trace 객체에 매핑되는 trace 필드가 있습니다. 추적은 콘솔과 API 모두에서 JSON 객체로 표시됩니다. 콘솔의 각 단계나 API의 Trace는 다음 추적 중 하나가 될 수 있습니다.

  • PreprocessingTrace - 사전 처리 단계의 입력과 출력을 추적합니다. 이 단계에서 에이전트는 사용자 입력을 컨텍스트화하고 분류하여 유효한지 확인합니다.

  • OrchestrationTrace - 오케스트레이션 단계의 입력과 출력을 추적합니다. 이 단계에서 에이전트는 입력을 해석하고, 작업 그룹을 간접 호출하고, 지식 기반을 쿼리합니다. 그런 다음 에이전트는 오케스트레이션을 계속하거나 사용자에게 응답하기 위해 출력을 반환합니다.

  • PostProcessingTrace - 에이전트가 오케스트레이션의 최종 출력을 처리하고 사용자에게 응답을 반환하는 방법을 결정하는 사후 처리 단계의 입력과 출력을 추적합니다.

  • FailureTrace - 단계가 실패한 이유를 추적합니다.

  • GuardrailTrace – Guardrail의 작업을 추적합니다.

각 추적(FailureTrace 제외)에는 ModelInvocationInput 객체가 포함됩니다. ModelInvocationInput 객체에는 이 단계에서 에이전트에 제공된 프롬프트와 함께 이 단계의 프롬프트 템플릿에 설정된 구성이 포함됩니다. 프롬프트 템플릿을 수정하는 방법에 대한 자세한 내용은 Amazon Bedrock의 고급 프롬프트 템플릿을 사용하여 에이전트의 정확도 향상 섹션을 참조하세요. ModelInvocationInput 객체의 구조는 다음과 같습니다.

{
    "traceId": "string",
    "text": "string",
    "type": "PRE_PROCESSING | ORCHESTRATION | ROUTING_CLASSIFIER | KNOWLEDGE_BASE_RESPONSE_GENERATION | POST_PROCESSING",
    "foundationModel:string",
    "inferenceConfiguration": {
        "maximumLength": number,
        "stopSequences": ["string"],
        "temperature": float,
        "topK": float,
        "topP": float
    },
    "promptCreationMode": "DEFAULT | OVERRIDDEN",
    "parserMode": "DEFAULT | OVERRIDDEN",
    "overrideLambda": "string"
}

다음 목록에서는 ModelInvocationInput 객체의 필드에 대해 설명합니다.

각 추적 유형에 대한 자세한 내용은 다음 섹션을 참조하세요.

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "metadata": {
             "usage": {
                  "inputToken":: int,
                  "outputToken":: int
           },
         "rawResponse": {
              "content": "string"
          }
        "parsedResponse": {
            "isValid": boolean,
            "rationale": "string"
        },
        "traceId": "string"
    }
}

PreProcessingTrace는 ModelInvocationInput 객체와 PreProcessingModelInvocationOutput 객체로 구성됩니다. PreProcessingModelInvocationOutput에는 다음 필드가 포함됩니다.

  • metadata - 파운데이션 모델 출력에 대한 다음 정보를 포함합니다.

    • usage - 파운데이션 모델 사용에 대한 다음 정보를 포함합니다.

      • inputTokens - 파운데이션 모델 사용의 입력 토큰에 대한 정보를 포함합니다.

      • outputTokens - 파운데이션 모델 사용의 출력 토큰에 대한 정보를 포함합니다.

  • rawResponse - 파운데이션 모델의 원시 출력을 포함합니다.

    • content - 파운데이션 모델의 원시 출력 콘텐츠입니다.

  • parsedResponse - 파싱된 사용자 프롬프트에 대한 다음 세부 정보가 들어 있습니다.

    • isValid - 사용자 프롬프트가 유효한지 여부를 지정합니다.

    • rationale - 에이전트가 취해야 할 다음 단계에 대한 이유를 지정합니다.

  • traceId - 추적의 고유 식별자입니다.

OrchestrationTrace는 ModelInvocationInput 객체와 OrchestrationModelInvocationOutput 객체, 그리고 Rationale, InvocationInput, Observation 객체의 가능한 조합으로 구성됩니다. OrchestrationModelInvocationOutput에는 다음 필드가 포함됩니다. Rationale, InvocationInput, Observation 객체에 대한 자세한 내용은 다음 탭을 선택하여 확인하세요.

{
    "modelInvocationInput": { // see above for details },
     "modelInvocationOutput": {
        "metadata": {
             "usage": {
                  "inputToken":: int,
                  "outputToken":: int
           },
         "rawResponse": {
              "content": "string"
          },
    "rationale": { ... },
    "invocationInput": { ... },
    "observation": { ... }
}

type가 AGENT_COLLABORATOR 이고 감독자 에이전트에 대해 라우팅이 활성화된 경우 OrchestrationModelInvocationOutput에는 다음 구조가 포함됩니다.

routingClassifierModelInvocationOutput: {
        traceId: "string",
        rawResponse: "string",
        routerClassifierParsedResponse: {...} 
        metadata: {
            inputTokens: "..."
            outputTokens: "..."    
        }
    }
Rationale

Rationale 객체에는 사용자 입력에 따른 에이전트의 추론이 포함됩니다. 구조는 다음과 같습니다.

{
       "traceId": "string",
       "text": "string"
    }

다음 목록에서는 Rationale 객체의 필드에 대해 설명합니다.

  • traceId - 추적 단계의 고유 식별자입니다.

  • text - 입력 프롬프트를 기반으로 한 에이전트의 추론 프로세스입니다.

InvocationInput

InvocationInput 객체에는 간접적으로 호출하거나 쿼리할 작업 그룹 또는 지식 기반에 입력할 정보가 들어 있습니다. 구조는 다음과 같습니다.

{
    "traceId": "string",
    "invocationType": "AGENT_COLLABORATOR" | "ACTION_GROUP | KNOWLEDGE_BASE | FINISH",
     "agentCollaboratorInvocationInput": { 
        // see below for details
    },
    "actionGroupInvocationInput": {
        // see below for details
    },
    "knowledgeBaseLookupInput": {
        "knowledgeBaseId": "string",
        "text": "string"
    }
}

다음 표에서는 InvocationInput 객체의 필드에 대해 설명합니다.

  • traceId - 추적의 고유 식별자입니다.

  • invocationType - 에이전트가 공동 작업자 에이전트, 작업 그룹 또는 지식 기반을 호출할지 아니면 세션을 종료할지 지정합니다.

  • agentCollaborationInvocationInput - 공동 작업자 에이전트에 대한 호출 입력을 포함합니다. 가 type AGENT_COLLABORATOR 이고 감독자 에이전트에 대해 라우팅이 활성화된 경우 나타납니다. 자세한 내용은 Amazon Bedrock Agents와 다중 에이전트 공동 작업 사용 단원을 참조하십시오.

    • agentCollaborationInvocationInput 구조는 다음과 같습니다.

      {
  "agentCollaboratorName": "string",
  "agentCollaboratorAliasArn": "string",
  "input": {
      "text": "string"           
     }
  }

      다음은 필드에 대한 설명입니다.

      • agentCollaboratorName - 감독자 에이전트와 연결된 공동 작업자 에이전트의 이름입니다.

      • agentCollaboratorAliasArn – 공동 작업자 에이전트의 별칭 Arn입니다.

      • input - 공동 작업자 에이전트의 입력 문자열입니다.

  • actionGroupInvocationInput - type이 ACTION_GROUP이면 표시됩니다. 자세한 내용은 작업 그룹에서 작업 정의 섹션을 참조하세요. 구조는 다음 중 하나일 수 있습니다.

    • 작업 그룹이 API 스키마로 정의된 경우 구조는 다음과 같습니다.

      {
    "actionGroupName": "string",
    "apiPath": "string",
    "verb": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "requestBody": {
        "content": {
            "<content-type>": [
                {
                    "name": "string",
                    "type": "string",
                    "value": "string"
                }   
            ]
        }
    },
    "executionType": "LAMBDA | RETURN_CONTROL",
    "invocationId": "string"
}

      다음은 필드에 대한 설명입니다.

      • actionGroupName - 에이전트가 간접 호출되어야 한다고 예측하는 작업 그룹의 이름입니다.

      • apiPath - API 스키마에 따라 직접 호출할 API 작업의 경로입니다.

      • verb - API 스키마에 따라 사용 중인 API 메서드입니다.

      • parameters - 객체 목록을 포함합니다. 각 객체에는 API 스키마에 정의된 대로 API 작업의 파라미터 이름, 유형 및 값이 포함됩니다.

      • requestBody - API 스키마에 정의된 대로 요청 본문과 해당 속성을 포함합니다.

      • executionType – 작업 이행이 Lambda 함수(LAMBDA)로 전달되는지 아니면 InvokeAgent 응답(RETURN_CONTROL)을 통해 제어가 반환되는지 여부입니다. 자세한 내용은 작업 이행 처리 섹션을 참조하세요.

      • invocationId – 간접 호출의 고유 식별자입니다. executionType이 RETURN_CONTROL인 경우에만 반환됩니다.

    • 작업 그룹이 함수 세부 정보로 정의된 경우 구조는 다음과 같습니다.

      {
    "actionGroupName": "string",
    "function": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "executionType": "LAMBDA | RETURN_CONTROL",
    "invocationId": "string"
}

      다음은 필드에 대한 설명입니다.

      • actionGroupName - 에이전트가 간접 호출되어야 한다고 예측하는 작업 그룹의 이름입니다.

      • function - 에이전트가 직접 호출되어야 한다고 예측하는 함수의 이름입니다.

      • parameters – 함수의 파라미터입니다.

      • executionType – 작업 이행이 Lambda 함수(LAMBDA)로 전달되는지 아니면 InvokeAgent 응답(RETURN_CONTROL)을 통해 제어가 반환되는지 여부입니다. 자세한 내용은 작업 이행 처리 섹션을 참조하세요.

      • invocationId – 간접 호출의 고유 식별자입니다. executionType이 RETURN_CONTROL인 경우에만 반환됩니다.

  • knowledgeBaseLookupInput - type이 KNOWLEDGE_BASE이면 표시됩니다. 자세한 내용은 Amazon Bedrock 지식 기반을 사용하여 데이터 검색 및 AI 응답 생성 섹션을 참조하세요. 지식 기반에 대한 다음과 같은 정보와 지식 기반에 대한 검색 쿼리가 포함되어 있습니다.

    • knowledgeBaseId - 에이전트가 조회하고 있는 지식 기반의 고유 식별자입니다.

    • text - 지식 기반에 대해 진행 중인 쿼리입니다.

Observation

관찰 객체에는 에이전트 공동 작업자, 작업 그룹 또는 지식 기반 또는 사용자에 대한 응답의 결과 또는 출력이 포함됩니다. 구조는 다음과 같습니다.

{
    "traceId": "string",
    "type": "AGENT_COLLABORATOR |ACTION_GROUP | KNOWLEDGE_BASE | REPROMPT | ASK_USER | FINISH",
    "agentCollaboratorInvocationOutput": { 
            "agentCollaboratorName": "string",
            "agentCollaboratorAliasArn": "string",
            "output": {
                "text": "string"
            },
    "actionGroupInvocation": {
        "text": "JSON-formatted string"
    },
    "knowledgeBaseLookupOutput": {
        "retrievedReferences": [
            {
                "content": {
                    "text": "string"
                },
                "location": {
                    "type": "S3",
                    "s3Location": {
                        "uri": "string"
                    }
                }
            },
            ...
        ]
    },
    "repromptResponse": {
        "source": "ACTION_GROUP | KNOWLEDGE_BASE | PARSER",
        "text": "string"
    },
    "finalResponse": {
        "text"
    }
}

다음 표에서는 Observation 객체의 필드에 대해 설명합니다.

  • traceId - 추적의 고유 식별자입니다.

  • type - 에이전트가 사용자를 재프롬프팅하거나, 추가 정보를 요청하거나, 대화를 종료하는 경우 에이전트 공동 작업자, 작업 그룹 또는 지식 기반의 결과에서 에이전트의 관찰이 반환되는지 여부를 지정합니다.

  • agentCollaboratorInvocationOutput - 공동 작업자 에이전트의 응답 또는 최종 응답을 포함합니다. 가 type AGENT_COLLABORATOR 이고 감독자 에이전트에 대해 라우팅이 활성화된 경우 나타납니다. 자세한 내용은 Amazon Bedrock Agents와 다중 에이전트 공동 작업 사용 단원을 참조하십시오. 각 응답에는 다음 필드가 포함됩니다.

    • agentCollaboratorName - 응답을 보내는 공동 작업자 에이전트의 이름입니다.

    • agentCollaboratorAliasArn - 응답을 보내는 공동 작업자 에이전트의 별칭 Arn입니다.

    • output - 공동 작업자 에이전트가 보낸 응답을 포함합니다.

  • actionGroupInvocationOutput - 작업 그룹이 간접 호출한 API 작업에서 반환된 JSON 형식의 문자열이 들어 있습니다. type이 ACTION_GROUP이면 표시됩니다. 자세한 내용은 정의 OpenAPI Amazon Bedrock에서 에이전트의 작업 그룹에 대한 스키마 섹션을 참조하세요.

  • knowledgeBaseLookupOutput - 프롬프트에 대한 응답과 관련된 지식 기반에서 검색된 텍스트를 데이터 소스의 Amazon S3 위치와 함께 포함합니다. type이 KNOWLEDGE_BASE이면 표시됩니다. 자세한 내용은 Amazon Bedrock 지식 기반을 사용하여 데이터 검색 및 AI 응답 생성 섹션을 참조하세요. retrievedReferences 목록의 각 객체에는 다음 필드가 포함됩니다.

    • content - 지식 기반 쿼리에서 반환되는 지식 기반의 text가 포함됩니다.

    • location - 반환된 텍스트가 검색된 데이터 소스의 Amazon S3 URI가 들어 있습니다.

  • repromptResponse - type이 REPROMPT이면 표시됩니다. 에이전트가 프롬프트를 다시 요청해야 하는 이유에 대한 source와 함께 다시 프롬프트를 요청하는 text가 포함됩니다.

  • finalResponse - type이 ASK_USER 또는 FINISH이면 표시됩니다. 사용자에게 자세한 정보를 요청하거나 사용자에 대한 응답인 text가 들어 있습니다.

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "rawResponse": {
            "content": "string"
        },
        "metadata": {
            "usage": {
                "inputToken": int,
                "outputToken": int    
             }     
         },
        "parsedResponse": {
            "text": "string"
        },
        "traceId": "string"
    }
}

PostProcessingTrace는 ModelInvocationInput 객체와 PostProcessingModelInvocationOutput 객체로 구성됩니다. PostProcessingModelInvocationOutput에는 다음 필드가 포함됩니다.

  • rawResponse - 파운데이션 모델의 원시 출력을 포함합니다.

    • content - 파운데이션 모델의 원시 출력 콘텐츠입니다.

  • metadata - 파운데이션 모델 출력에 대한 다음 정보를 포함합니다.

    • usage - 파운데이션 모델 사용에 대한 다음 정보를 포함합니다.

      • inputTokens - 파운데이션 모델 사용의 입력 토큰에 대한 정보를 포함합니다.

      • outputTokens - 파운데이션 모델 사용의 출력 토큰에 대한 정보를 포함합니다.

  • parsedResponse - 텍스트가 파서 함수로 처리된 후 사용자에게 반환되는 text가 포함되어 있습니다.

  • traceId - 추적의 고유 식별자입니다.

{
    "failureReason": "string",
    "traceId": "string"
}

다음 표에서는 FailureTrace 객체의 필드에 대해 설명합니다.

  • failureReason - 단계가 실패한 이유입니다.

  • traceId - 추적의 고유 식별자입니다.

{
    "action": "GUARDRAIL_INTERVENED" | "NONE",
    "inputAssessments": [GuardrailAssessment],
    "outputAssessments": [GuardrailAssessment]
}

다음 목록은 GuardrailAssessment 객체의 필드를 설명합니다.

  • action – 입력 데이터에 가드레일이 개입되었는지 여부를 나타냅니다. 옵션은 GUARDRAIL_INTERVENED 또는 NONE입니다.

  • inputAssessments - 사용자 입력에 대한 Guardrail 평가의 세부 정보입니다.

  • outputAssessments – 응답에 대한 Guardrail 평가의 세부 정보입니다.

GuardrailAssessment 객체 및 Guardrail 테스트에 대한 자세한 내용은 가드레일 테스트 섹션을 참조하세요.

GuardrailAssessment 예제:

{
    "topicPolicy": {
        "topics": [{
            "name": "string",
            "type": "string",
            "action": "string"
        }]
    },
    "contentPolicy": {
        "filters": [{
            "type": "string",
            "confidence": "string",
            "action": "string"
        }]
    },
    "wordPolicy": {
        "customWords": [{
            "match": "string",
            "action": "string"
        }],
        "managedWordLists": [{
            "match": "string",
            "type": "string",
            "action": "string"
        }]
    },
    "sensitiveInformationPolicy": {
        "piiEntities": [{
            "type": "string",
            "match": "string",
            "action": "string"
        }],
        "regexes": [{
            "name": "string",
            "regex": "string",
            "match": "string",
            "action": "string"
        }]
    }
}