Method: projects.locations.collections.engines.agentTrajectories.write

내부 모니터링 가능성 로깅을 위해 단일 에이전트 턴의 실행 트레이저리를 작성합니다. 이 메서드는 퍼스트 파티 에이전트 클라이언트 (예: Gemini Enterprise 데스크톱 Cowork 에이전트)에서 사용됩니다. 로깅은 엔진의 ObservabilityConfig에 따라 관리됩니다. 민감한 콘텐츠 로깅이 사용 설정되지 않으면 콘텐츠를 포함하는 속성이 수정되고, 궤적은 디버깅을 위해 고정된 Google 내부 GCS 버킷에 JSON 객체로 작성됩니다 (고객 프로젝트에는 작성되지 않음). 사용자 이벤트 또는 추천 스토어에 유지되지 않습니다.

HTTP 요청


POST https://discoveryengine.googleapis.com/v1/{parent=projects/*/locations/*/collections/*/engines/*}/agentTrajectories:write

URL은 gRPC 트랜스코딩 구문을 사용합니다.

경로 매개변수

매개변수
parent

string

필수 항목입니다. 궤적이 속한 Engine(projects/{project}/locations/{location}/collections/{collection}/engines/{engine} 형식) 관측 가능성 로깅은 이 엔진의 ObservabilityConfig에 따라 관리됩니다. 궤적은 엔진에 관측 가능성이 사용 설정된 경우에만 로깅되며 (고정된 Google 내부 GCS 버킷에 JSON 객체로 작성됨) 콘텐츠 관련 속성은 민감한 로깅이 사용 설정된 경우에만 포함됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
필드
agentTrajectory

object (AgentTrajectory)

필수 항목입니다. 로깅할 에이전트 궤적입니다.

응답 본문

UserEventService.WriteAgentTrajectory 메서드의 응답 메시지입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "acceptedSpanCount": integer
}
필드
acceptedSpanCount

integer

모니터링 가능성 로깅을 위해 수락된 스팬 수입니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

자세한 내용은 Authentication Overview에서 확인하세요.

IAM 권한

parent 리소스에 대해서는 다음 IAM 권한이 필요합니다.

  • discoveryengine.engines.createEngineUserData

자세한 내용은 IAM 문서를 참조하세요.

AgentTrajectory

AgentTrajectory는 OpenTelemetry 생성형 AI 시맨틱 규칙을 기반으로 모델링된 단일 에이전트 턴의 실행 트레이스를 캡처합니다. 내부 관측 가능성 로깅을 위해서만 퍼스트 파티 클라이언트 (예: Gemini Enterprise 데스크톱 Cowork 에이전트)에 의해 보고되며 사용자 이벤트 / 추천 저장소에 유지되지 않습니다.

서버는 엔진의 ObservabilityConfig에서 로깅을 관리하고, 민감한 콘텐츠 로깅이 사용 설정되지 않은 경우 콘텐츠가 포함된 속성을 수정하고, 디버깅을 위해 궤적을 고정된 Google 내부 GCS 버킷에 JSON 객체로 작성합니다 (고객 프로젝트에는 작성하지 않음).

JSON 표현 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
필드
spans[]

object (Span)

필수 항목입니다. 이 에이전트 턴을 구성하는 스팬입니다. 모든 스팬은 동일한 Span.trace_id을 공유해야 합니다(MUST).
sessionId

string

(선택사항) 이 턴이 속한 에이전트 세션의 고유 식별자입니다.
resourceAttributes

map (key: string, value: string)

(선택사항) OpenTelemetry 리소스 시맨틱 규칙 (예: service.name, gen_ai.agent.name, gen_ai.agent.id)을 따르는 모든 스팬에서 공유되는 리소스 수준 속성입니다. 기본적으로 관측 가능성 로깅이 선택됩니다.

스팬

OpenTelemetry 스팬 데이터 모델과 정렬된 에이전트 궤적 내의 단일 스팬입니다.

JSON 표현 
{
  "traceId": string,
  "spanId": string,
  "parentSpanId": string,
  "displayName": string,
  "spanKind": enum (SpanKind),
  "startTime": string,
  "endTime": string,
  "attributes": {
    string: string,
    ...
  },
  "contentAttributes": {
    string: string,
    ...
  },
  "status": {
    object (Status)
  },
  "events": [
    {
      object (Event)
    }
  ]
}
필드
traceId

string

필수 항목입니다. 턴의 모든 스팬에서 공유되는 32개의 16진수 문자 (16바이트) 트레이스 ID입니다.
spanId

string

필수 항목입니다. 트레이스 내에서 이 스팬을 고유하게 식별하는 16개의 16진수 문자 (8바이트) 스팬 ID입니다.
parentSpanId

string

(선택사항) 이 스팬의 상위 스팬 ID입니다(있는 경우). 루트 스팬의 경우 비어 있습니다.
displayName

string

필수 항목입니다. 스팬의 인간이 읽을 수 있는 이름입니다 (예: invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

(선택사항) 스팬의 종류입니다.
startTime

string (Timestamp format)

필수 항목입니다. 스팬의 시작 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
endTime

string (Timestamp format)

필수 항목입니다. 스팬의 종료 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
attributes

map (key: string, value: string)

(선택사항) OpenTelemetry 생성형 AI 시맨틱 규칙을 따르는 콘텐츠가 아닌 스팬 속성 (예: gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). 숫자 값은 문자열로 인코딩됩니다. 이러한 항목은 기본적으로 모니터링 가능성 로깅이 선택되어 있습니다.
contentAttributes

map (key: string, value: string)

(선택사항) 콘텐츠가 포함된 속성 (예: 프롬프트, 대답, 도구 인수 및 결과) 이러한 데이터는 기본적으로 모니터링 가능성 로깅에서 선택 해제되며 고객이 민감한 콘텐츠 로깅을 사용 설정한 경우에만 로깅됩니다.
status

object (Status)

(선택사항) 스팬의 상태입니다. code은 google.rpc.Code입니다. OK (0)은 성공을 나타내고 0이 아닌 코드는 오류를 나타냅니다.
events[]

object (Event)

(선택사항) 스팬 중에 발생한 시간 제한 이벤트입니다.

SpanKind

OpenTelemetry SpanKind와 일치하는 스팬의 종류입니다.

열거형
SPAN_KIND_UNSPECIFIED 지정되지 않음. INTERNAL로 처리됩니다.
INTERNAL 에이전트 내의 내부 작업 (예: invoke_agent)입니다.
SERVER 동기 수신 요청 핸들러입니다.
CLIENT 동기식 아웃바운드 요청 (예: 모델 또는 도구 호출)
PRODUCER 메시지의 비동기 프로듀서입니다.
CONSUMER 메시지의 비동기 소비자입니다.

이벤트

스팬 중에 발생한 시간 제한 이벤트입니다 (예: 스트리밍된 청크).

JSON 표현 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
필드
displayName

string

필수 항목입니다. 인간이 읽을 수 있는 이벤트 이름입니다.
eventTime

string (Timestamp format)

필수 항목입니다. 이벤트가 발생한 실제 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
attributes

map (key: string, value: string)

(선택사항) 이벤트를 설명하는 콘텐츠가 아닌 속성입니다.