# Google ADK
<a name="supported-frameworks-google-adk"></a>

Halaman ini menjelaskan cara instrumen [agen Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/), bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

 **Topik** 
+  [Instrumen agen Anda](#google-adk-instrument) 
+  [Bagaimana rentang diidentifikasi](#google-adk-span-identification) 
+  [Bagaimana bidang evaluasi diekstraksi](#google-adk-extraction) 
  +  [Dari catatan acara](#google-adk-extraction-event-records) 
  +  [Dari atribut span](#google-adk-extraction-attributes) 
+  [Contoh membentang dengan catatan acara](#google-adk-examples-with) 
+  [Contoh membentang tanpa catatan peristiwa](#google-adk-examples-without) 

## Instrumen agen Anda
<a name="google-adk-instrument"></a>

Anda dapat menginstrumentasikan agen Google ADK dengan library **OpenInference**instrumentasi ()`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](supported-frameworks.md#supported-frameworks-setup).

## Bagaimana rentang diidentifikasi
<a name="google-adk-span-identification"></a>

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` `CHAIN`Rentang luar membawa prompt pengguna; AgentCore Evaluasi menggunakannya sebagai rentang agen pemanggilan.

## Bagaimana bidang evaluasi diekstraksi
<a name="google-adk-extraction"></a>

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](supported-frameworks-telemetry.md).

### Dari catatan acara
<a name="google-adk-extraction-event-records"></a>

Ketika telemetri dibagi, AgentCore Evaluasi membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:
+  **Prompt pengguna**: dari catatan peristiwa rentang agen pemanggilan, di`body.input`. AgentCore Evaluasi membuka teks. `new_message.parts`
+  **Respons agen**: dari catatan peristiwa rentang agen pemanggilan, di`body.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` dan`body.output`.

Sebagai contoh, lihat [Contoh bentang dengan catatan peristiwa](#google-adk-examples-with).

### Dari atribut span
<a name="google-adk-extraction-attributes"></a>

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 dari`tool.name`, dan argumen dan hasil dari `input.value` dan`output.value`, pada rentang alat eksekusi.

Sebagai contoh, lihat [Contoh rentang tanpa catatan peristiwa](#google-adk-examples-without).

## Contoh membentang dengan catatan acara
<a name="google-adk-examples-with"></a>

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.

**Example**  
`openinference.span.kind`Atribut (`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 bawah`new_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\"}"
        }
      ]
    }
  }
}
```
`openinference.span.kind`Atribut (`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\": [ ... ]}}"
        }
      ]
    }
  }
}
```
`openinference.span.kind`Atribut (`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
<a name="google-adk-examples-without"></a>

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.

**Example**  
`input.value`Atribut menahan prompt pengguna (bersarang di bawah`new_message.parts`), dan `output.value` atribut menahan respons agen (bersarang di bawah`content.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"
  }
}
```
`input.value`Atribut 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"
  }
}
```
`openinference.span.kind`Atribut (`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"
  }
}
```