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

Menulis trajektori eksekusi satu giliran agen untuk logging kemampuan pengamatan internal. Metode ini digunakan oleh klien agen pihak pertama (misalnya, agen Cowork desktop Gemini Enterprise). Logging dibatasi pada ObservabilityConfig mesin; atribut yang berisi konten disamarkan kecuali jika logging konten sensitif diaktifkan, dan lintasan ditulis sebagai objek JSON ke bucket GCS internal Google yang tetap untuk proses debug (tidak pernah ke project pelanggan). TIDAK dipertahankan ke penyimpanan rekomendasi atau peristiwa pengguna.

Permintaan HTTP


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

URL ini menggunakan sintaksis gRPC Transcoding.

Parameter jalur

Parameter
parent

string

Wajib. Engine yang menjadi bagian dari lintasan, dalam bentuk projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. Pencatatan log kemampuan observasi dibatasi pada ObservabilityConfig mesin ini: lintasan hanya dicatat (ditulis sebagai objek JSON ke bucket GCS internal Google yang tetap) jika kemampuan observasi diaktifkan untuk mesin, dan atribut yang berisi konten hanya disertakan jika pencatatan log sensitif diaktifkan.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Kolom
agentTrajectory

object (AgentTrajectory)

Wajib. Trajektori agen yang akan dicatat.

Isi respons

Pesan respons untuk metode UserEventService.WriteAgentTrajectory.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "acceptedSpanCount": integer
}
Kolom
acceptedSpanCount

integer

Jumlah span yang diterima untuk logging kemampuan observasi.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • 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

Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.

Izin IAM

Memerlukan izin IAM berikut pada resource parent:

  • discoveryengine.engines.createEngineUserData

Untuk mengetahui informasi selengkapnya, lihat dokumentasi IAM.

AgentTrajectory

AgentTrajectory merekam rekaman aktivitas eksekusi satu giliran agen, yang dimodelkan berdasarkan konvensi semantik GenAI OpenTelemetry. Peristiwa ini dilaporkan oleh klien pihak pertama (misalnya, agen Cowork desktop Gemini Enterprise) hanya untuk logging kemampuan observasi internal; peristiwa ini tidak disimpan ke penyimpanan peristiwa / rekomendasi pengguna.

Server membatasi logging di ObservabilityConfig mesin, menyamarkan atribut yang berisi konten kecuali jika logging konten sensitif diaktifkan, dan menulis lintasan sebagai objek JSON ke bucket GCS internal Google yang tetap untuk proses debug (tidak pernah ke project pelanggan).

Representasi JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Kolom
spans[]

object (Span)

Wajib. Rentang yang membentuk giliran agen ini. Semua rentang HARUS memiliki Span.trace_id yang sama.
sessionId

string

Opsional. ID unik untuk sesi agen yang memiliki giliran ini.
resourceAttributes

map (key: string, value: string)

Opsional. Atribut tingkat resource yang dibagikan oleh semua rentang, mengikuti konvensi semantik resource OpenTelemetry (misalnya, service.name, gen_ai.agent.name, gen_ai.agent.id). Atribut ini diaktifkan untuk logging kemampuan pengamatan secara default.

Span

Rentang tunggal dalam lintasan agen, selaras dengan model data rentang OpenTelemetry.

Representasi 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)
    }
  ]
}
Kolom
traceId

string

Wajib. ID trace 32 karakter heksadesimal (16 byte) yang digunakan bersama oleh semua rentang giliran.
spanId

string

Wajib. ID rentang 16 karakter heksadesimal (8 byte) yang secara unik mengidentifikasi rentang ini dalam rekaman aktivitas.
parentSpanId

string

Opsional. ID rentang induk rentang ini, jika ada. Kosong untuk rentang root.
displayName

string

Wajib. Nama yang dapat dibaca manusia untuk rentang (misalnya, invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

Opsional. Jenis rentang.
startTime

string (Timestamp format)

Wajib. Waktu mulai rentang.

Menggunakan RFC 3339 yang outputnya akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Wajib. Waktu berakhir rentang.

Menggunakan RFC 3339 yang outputnya akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Opsional. Atribut rentang non-konten yang mengikuti konvensi semantik GenAI OpenTelemetry (misalnya, gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). Nilai numerik dienkode sebagai string. Objek ini diikutsertakan dalam logging kemampuan observasi secara default.
contentAttributes

map (key: string, value: string)

Opsional. Atribut yang memuat konten (misalnya, perintah, respons, argumen dan hasil alat). Secara default, opsi ini TIDAK diikutsertakan dalam logging kemampuan pengamatan dan hanya dicatat saat pelanggan telah mengaktifkan logging konten sensitif.
status

object (Status)

Opsional. Status rentang. code adalah google.rpc.Code; OK (0) menunjukkan keberhasilan dan kode bukan nol menunjukkan error.
events[]

object (Event)

Opsional. Peristiwa berjangka waktu yang terjadi selama rentang waktu.

SpanKind

Jenis rentang, selaras dengan SpanKind OpenTelemetry.

Enum
SPAN_KIND_UNSPECIFIED Tidak ditentukan. Diperlakukan sebagai INTERNAL.
INTERNAL Operasi internal dalam agen (misalnya, invoke_agent).
SERVER Handler permintaan masuk sinkron.
CLIENT Permintaan keluar sinkron (misalnya, panggilan model atau alat).
PRODUCER Produser pesan asinkron.
CONSUMER Konsumen pesan asinkron.

Acara

Peristiwa berjangka waktu yang terjadi selama rentang (misalnya, chunk yang di-streaming).

Representasi JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Kolom
displayName

string

Wajib. Nama yang dapat dibaca manusia untuk acara.
eventTime

string (Timestamp format)

Wajib. Waktu jam dinding saat peristiwa terjadi.

Menggunakan RFC 3339 yang outputnya akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Opsional. Atribut non-konten yang mendeskripsikan acara.