Instrumentasikan agen Anda Bagaimana rentang diidentifikasi Bagaimana bidang evaluasi diekstraksi Contoh rentang dalam telemetri terpisah Contoh rentang dalam telemetri terpadu

Google ADK

Halaman ini menjelaskan cara instrumen agen Google Agent Development Kit (ADK), bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

Topik

Instrumentasikan agen Anda
Bagaimana rentang diidentifikasi
Bagaimana bidang evaluasi diekstraksi
- Dari catatan acara
- Dari atribut rentang
Contoh rentang dalam telemetri terpisah
Contoh rentang dalam telemetri terpadu

Instrumentasikan agen Anda

Anda dapat menginstrumenkan agen Google ADK dengan pustaka OpenInference instrumentasi ()openinference-instrumentation-google-adk. Perpustakaan ini memancarkan telemetri dengan nama ruang lingkupopeninference.instrumentation.google_adk, yang dibaca oleh Amazon Bedrock AgentCore Evaluations.

Saat agen Anda berjalan dengan AWS Distro for OpenTelemetry (ADOT), seperti pada Amazon Bedrock AgentCore Runtime, Anda tidak perlu menambahkan kode instrumentasi eksplisit. Menambahkan pustaka instrumentasi ke dependensi proyek Anda sudah cukup. ADOT menemukannya saat startup dan mengaktifkannya secara otomatis.

Tambahkan pustaka instrumentasi ke dependensi Anda.

catatan

Gunakan versi 0.1.13 atau yang lebih baru. Ini adalah versi paling awal yang diuji dengan layanan evaluasi.

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-google-adk>=0.1.13",
]

catatan

Instrumentasi adalah salah satu langkah dalam mengatur observabilitas. Untuk mengekspor telemetri untuk evaluasi, selesaikan penyiapan lengkap di Menyi apkan observ abilitas.

Bagaimana rentang diidentifikasi

Google ADK diinstrumentasikan dengan OpenInference konvensi, sehingga AgentCore Evaluasi mengklasifikasikan rentang menggunakan atribut. openinference.span.kind

Jenis rentang	Mengidentifikasi atribut
Memanggil agen	`openinference.span.kind`= `CHAIN` atau `AGENT`
Jalankan alat	`openinference.span.kind` = `TOOL`
Inferensi	`openinference.span.kind` = `LLM`

Google ADK memancarkan pohon rentang bersarang: invocation span luar (CHAIN) membungkus agent_run span (AGENT), yang pada gilirannya membungkus rentang call_llm (LLM) dan execute_tool (TOOL). Rent CHAIN ang luar membawa prompt pengguna; AgentCore Evaluasi menggunakannya sebagai rentang agen pemanggilan.

Bagaimana bidang evaluasi diekstraksi

Google ADK membungkus konten percakapannya dalam format konten Gemini. Prompt pengguna bersarang di bawah new_message objek sebagai{"new_message": {"parts": [{"text": "…"}], "role": "user"}}, dan respons agen bersarang di bawah content objek sebagai. {"content": {"parts": [{"text": "…"}], "role": "model"}} AgentCore Evaluasi membuka struktur ini dan menggabungkan parts teks dengan baris baru. Definisi alat tiba sebagai permintaan Gemini berseri; AgentCore Evaluasi membaca alat yang tersedia dariconfig.tools[].function_declarations[].

Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengi openinference.span.kind dentifikasi () berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat Peng aturan dan pengiriman telemetri.

Dari catatan acara

Dengan telemetri terpisah, AgentCore Evaluasi membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:

Permintaan pengguna: dari catatan peristiwa span agen pemanggilan, dibody.input. AgentCore Evaluasi membuka new_message.parts teks.
Respon agen: dari catatan peristiwa span agen invoke, dibody.output. AgentCore Evaluasi membuka content.parts teks.
Panggilan alat: nama alat dari tool.name atribut pada rentang alat eksekusi. Argumen alat dan hasil berasal dari catatan peristiwa span itu, di body.input danbody.output.

Untuk informasi selengkapnya, lihat Contoh rentang dalam telem etri terpisah.

Dari atribut rentang

Dengan telemetri terpadu, konten yang sama tetap pada rentang sebagai atribut:

Prompt pengguna dan respons agen: dari input.value dan output.value pada rentang agen pemanggilan. AgentCore Evaluasi membuka content.parts teks new_message.parts dan.
Panggilan alat: nama alat daritool.name, dan argumen serta hasil dari input.value danoutput.value, pada rentang alat eksekusi.

Untuk informasi selengkapnya, lihat Contoh rentang dalam telem etri terpadu.

Contoh rentang dalam telemetri terpisah

Dengan telemetri terpisah, rentang membawa atribut pengidentifikasi dan konten hidup dalam catatan peristiwa yang berkorelasi. Contoh berikut berasal dari agen perencanaan perjalanan Google ADK yang digunakan di Amazon Bedrock Runtime. AgentCore

catatan

Contoh-contoh ini bukan rentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh

Invoke agent span

A openinference.span.kind tribut (CHAIN) pada invocation rentang luar mengidentifikasi ini sebagai rentang agen pemanggilan. Rentang tidak membawa konten percakapan; itu hidup dalam catatan peristiwa yang berkorelasi.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "70f2e87a30c34420",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "user.id": "default_user",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Catatan peristiwa yang berkorelasi membawa percakapan. Prompt pengguna bersarang di bawahnew_message.parts, dan respons agen bersarang di bawah. content.parts


{
  "spanId": "70f2e87a30c34420",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "{\"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}, \"state_delta\": null, \"run_config\": null}"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you with your travel plans! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}"
        }
      ]
    }
  }
}

Execute tool span

A openinference.span.kind tribut (TOOL) mengidentifikasi ini sebagai rentang alat eksekusi; tool.name memegang nama alat. Argumen alat dan hasil hidup dalam catatan peristiwa yang berkorelasi.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "9028a8dd94943456",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "FunctionTool",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "9028a8dd94943456",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}"
        }
      ]
    }
  }
}

Inference span

A openinference.span.kind tribut (LLM) pada call_llm rentang mengidentifikasi ini sebagai rentang inferensi. Ini membawa metadata model dan, dalam indeks llm.input_messages.* dan llm.output_messages.* atribut, pesan untuk panggilan model.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1c4e5f8a2b9d0e73",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Contoh rentang dalam telemetri terpadu

Dengan telemetri terpadu, konten yang sama tetap pada atribut rentang dan tidak ada catatan peristiwa terpisah yang dihasilkan. Contoh berikut berasal dari agen perencanaan perjalanan Google ADK.

catatan

Contoh-contoh ini bukan rentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh

Invoke agent span

A input.value tribut menyimpan prompt pengguna (bersarang di bawahnew_message.parts), dan output.value atribut menyimpan respons agen (bersarang di bawahcontent.parts).


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "31ea3d5882dac680",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.value": "{\"user_id\": \"test_user\", \"session_id\": \"sea-nyc-trip-2-turns-google-adk-unified\", \"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}}",
    "input.mime_type": "application/json",
    "output.value": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you plan your trip! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

A input.value tribut menyimpan argumen alat, dan output.value atribut menyimpan hasil alat.


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "b64c37adefae74f0",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

A openinference.span.kind tribut (LLM) pada call_llm rentang mengidentifikasi ini sebagai rentang inferensi. Pesan untuk panggilan model sebaris pada llm.output_messages.* atribut llm.input_messages.* dan indeks.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "2d5f6a9b3c0e1f84",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

LlamaIndex

SDK Agen Claude