Instrumen agen Anda Bagaimana rentang diidentifikasi Bagaimana bidang evaluasi diekstraksi Contoh membentang dengan catatan acara Contoh membentang tanpa catatan peristiwa

Google ADK

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

Topik

Instrumen agen Anda
Bagaimana rentang diidentifikasi
Bagaimana bidang evaluasi diekstraksi
- Dari catatan acara
- Dari atribut span
Contoh membentang dengan catatan acara
Contoh membentang tanpa catatan peristiwa

Instrumen agen Anda

Anda dapat menginstrumentasikan agen Google ADK dengan library OpenInferenceinstrumentasi ()openinference-instrumentation-google-adk. Pustaka ini memancarkan telemetri dengan nama lingkup, openinference.instrumentation.google_adk yang dibaca Amazon Bedrock AgentCore Evaluations.

Saat agen Anda berjalan dengan AWS Distro for OpenTelemetry (ADOT), seperti di 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 pengaturan lengkap di Siapkan observabilitas.

Bagaimana rentang diidentifikasi

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

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

Google ADK memancarkan pohon bentang bersarang: bentang luar (CHAIN) membungkus invocation agent_run span (AGENT), yang pada gilirannya membungkus rentang () dan call_llm (LLM). execute_tool TOOL CHAINRentang 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 teks dengan baris baru. parts Definisi alat tiba sebagai permintaan Gemini serial; AgentCore Evaluasi membaca alat yang tersedia dari. config.tools[].function_declarations[]

Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengidentifikasi (openinference.span.kind) berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat Rentang, catatan peristiwa, dan sinyal telemetri.

Dari catatan acara

Ketika telemetri dibagi, AgentCore Evaluasi membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:

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

Sebagai contoh, lihat Contoh bentang dengan catatan peristiwa.

Dari atribut span

Ketika telemetri tidak dibagi, 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 dan teks. new_message.parts content.parts
Panggilan alat: nama alat daritool.name, dan argumen dan hasil dari input.value danoutput.value, pada rentang alat eksekusi.

Sebagai contoh, lihat Contoh rentang tanpa catatan peristiwa.

Contoh membentang dengan catatan acara

Ketika telemetri dibagi, 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 bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh

Invoke agent span

openinference.span.kindAtribut (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

openinference.span.kindAtribut (TOOL) mengidentifikasi ini sebagai rentang alat eksekusi; tool.name memegang nama alat. Argumen dan hasil alat 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

openinference.span.kindAtribut (LLM) pada call_llm rentang mengidentifikasi ini sebagai rentang inferensi. Ini membawa metadata model dan, dalam diindeks 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 membentang tanpa catatan peristiwa

Ketika telemetri tidak dibagi, 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 bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh

Invoke agent span

input.valueAtribut menahan prompt pengguna (bersarang di bawahnew_message.parts), dan output.value atribut menahan 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

input.valueAtribut memegang argumen alat, dan output.value atribut memegang 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

openinference.span.kindAtribut (LLM) pada call_llm rentang mengidentifikasi ini sebagai rentang inferensi. Pesan untuk panggilan model sebaris pada diindeks llm.input_messages. dan atribut. llm.output_messages.


{
  "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

Agen Claude SDK